trycourier 4.18.2 → 4.19.0

data/lib/courier/resources/users/preferences.rb

@@ -32,6 +32,102 @@ module Courier
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Users::PreferenceBulkReplaceParams} for more details.
+        #
+        # 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.
+        #
+        # @overload bulk_replace(user_id, topics:, tenant_id: nil, request_options: {})
+        #
+        # @param user_id [String] Path param: A unique identifier associated with the user whose preferences you w
+        #
+        # @param topics [Array<Courier::Models::Users::PreferenceBulkReplaceParams::Topic>] Body param: The complete set of topic overrides for the user. Up to 50 topics ma
+        #
+        # @param tenant_id [String, nil] Query param: Update the preferences of a user for this specific tenant context.
+        #
+        # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Courier::Models::Users::PreferenceBulkReplaceResponse]
+        #
+        # @see Courier::Models::Users::PreferenceBulkReplaceParams
+        def bulk_replace(user_id, params)
+          query_params = [:tenant_id]
+          parsed, options = Courier::Users::PreferenceBulkReplaceParams.dump_request(params)
+          query = Courier::Internal::Util.encode_query_params(parsed.slice(*query_params))
+          @client.request(
+            method: :put,
+            path: ["users/%1$s/preferences", user_id],
+            query: query,
+            body: parsed.except(*query_params),
+            model: Courier::Models::Users::PreferenceBulkReplaceResponse,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Users::PreferenceBulkUpdateParams} for more details.
+        #
+        # 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.
+        #
+        # @overload bulk_update(user_id, topics:, tenant_id: nil, request_options: {})
+        #
+        # @param user_id [String] Path param: A unique identifier associated with the user whose preferences you w
+        #
+        # @param topics [Array<Courier::Models::Users::PreferenceBulkUpdateParams::Topic>] Body param: The topics to create or update. Between 1 and 50 topics may be provi
+        #
+        # @param tenant_id [String, nil] Query param: Update the preferences of a user for this specific tenant context.
+        #
+        # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Courier::Models::Users::PreferenceBulkUpdateResponse]
+        #
+        # @see Courier::Models::Users::PreferenceBulkUpdateParams
+        def bulk_update(user_id, params)
+          query_params = [:tenant_id]
+          parsed, options = Courier::Users::PreferenceBulkUpdateParams.dump_request(params)
+          query = Courier::Internal::Util.encode_query_params(parsed.slice(*query_params))
+          @client.request(
+            method: :post,
+            path: ["users/%1$s/preferences", user_id],
+            query: query,
+            body: parsed.except(*query_params),
+            model: Courier::Models::Users::PreferenceBulkUpdateResponse,
+            options: options
+          )
+        end
+
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Users::PreferenceDeleteTopicParams} for more details.
         #

data/lib/courier/resources/workspace_preferences/topics.rb

@@ -11,7 +11,7 @@ module Courier
         # 404 if the workspace preference does not exist. The topic id is generated and
         # returned.
         #
-        # @overload create(section_id, default_status:, name:, allowed_preferences: nil, include_unsubscribe_header: nil, routing_options: nil, topic_data: nil, request_options: {})
+        # @overload create(section_id, default_status:, name:, allowed_preferences: nil, description: nil, include_unsubscribe_header: nil, routing_options: nil, topic_data: nil, request_options: {})
         #
         # @param section_id [String] Id of the workspace preference to create the topic in.
         #
@@ -21,6 +21,8 @@ module Courier
         #
         # @param allowed_preferences [Array<Symbol, Courier::Models::WorkspacePreferenceTopicCreateRequest::AllowedPreference>, nil] Preference controls a recipient may customize for this topic. Defaults to empty
         #
+        # @param description [String, nil] Optional description shown under the topic on the hosted preferences page.
+        #
         # @param include_unsubscribe_header [Boolean, nil] Whether to include a list-unsubscribe header on emails for this topic.
         #
         # @param routing_options [Array<Symbol, Courier::Models::ChannelClassification>, nil] Default channels delivered for this topic. Defaults to empty if omitted.
@@ -126,7 +128,7 @@ module Courier
         # Replace a topic within a workspace preference. Full document replacement;
         # missing optional fields are cleared. Same 404 rules as GET.
         #
-        # @overload replace(topic_id, section_id:, default_status:, name:, allowed_preferences: nil, include_unsubscribe_header: nil, routing_options: nil, topic_data: nil, request_options: {})
+        # @overload replace(topic_id, section_id:, default_status:, name:, allowed_preferences: nil, description: nil, include_unsubscribe_header: nil, routing_options: nil, topic_data: nil, request_options: {})
         #
         # @param topic_id [String] Path param: Id of the subscription preference topic.
         #
@@ -138,6 +140,8 @@ module Courier
         #
         # @param allowed_preferences [Array<Symbol, Courier::Models::WorkspacePreferenceTopicReplaceRequest::AllowedPreference>, nil] Body param: Preference controls a recipient may customize. Omit to clear.
         #
+        # @param description [String, nil] Body param: Optional description shown under the topic on the hosted preferences
+        #
         # @param include_unsubscribe_header [Boolean, nil] Body param: Whether to include a list-unsubscribe header on emails for this topi
         #
         # @param routing_options [Array<Symbol, Courier::Models::ChannelClassification>, nil] Body param: Default channels delivered for this topic. Omit to clear.

data/lib/courier/resources/workspace_preferences.rb

@@ -10,10 +10,12 @@ module Courier
       # returned. Topics are created inside a workspace preference via POST
       # /preferences/sections/{section_id}/topics.
       #
-      # @overload create(name:, has_custom_routing: nil, routing_options: nil, request_options: {})
+      # @overload create(name:, description: nil, has_custom_routing: nil, routing_options: nil, request_options: {})
       #
       # @param name [String] Human-readable name for the workspace preference.
       #
+      # @param description [String, nil] Optional description shown under the section on the hosted preferences page.
+      #
       # @param has_custom_routing [Boolean, nil] Whether the workspace preference defines custom routing for its topics.
       #
       # @param routing_options [Array<Symbol, Courier::Models::ChannelClassification>, nil] Default channels for the workspace preference. Defaults to empty if omitted.
@@ -94,11 +96,20 @@ module Courier
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::WorkspacePreferencePublishParams} for more details.
+      #
       # Publish the workspace's preferences page. Takes a snapshot of every workspace
       # preference with its topics under a new published version, making the current
       # state visible on the hosted preferences page (non-draft).
       #
-      # @overload publish(request_options: {})
+      # @overload publish(brand_id: nil, description: nil, heading: nil, request_options: {})
+      #
+      # @param brand_id [String, nil] Brand for the hosted page - "default" (workspace default brand), "none" (no bran
+      #
+      # @param description [String, nil] Description shown under the heading on the hosted preferences page.
+      #
+      # @param heading [String, nil] Heading shown at the top of the hosted preferences page.
       #
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -106,23 +117,30 @@ module Courier
       #
       # @see Courier::Models::WorkspacePreferencePublishParams
       def publish(params = {})
+        parsed, options = Courier::WorkspacePreferencePublishParams.dump_request(params)
         @client.request(
           method: :post,
           path: "preferences/publish",
+          body: parsed,
           model: Courier::PublishPreferencesResponse,
-          options: params[:request_options]
+          options: options
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::WorkspacePreferenceReplaceParams} for more details.
+      #
       # Replace a workspace preference. Full document replacement; missing optional
       # fields are cleared. Topics attached to the workspace preference are unaffected.
       #
-      # @overload replace(section_id, name:, has_custom_routing: nil, routing_options: nil, request_options: {})
+      # @overload replace(section_id, name:, description: nil, has_custom_routing: nil, routing_options: nil, request_options: {})
       #
       # @param section_id [String] Id of the workspace preference.
       #
       # @param name [String] Human-readable name for the workspace preference.
       #
+      # @param description [String, nil] Optional description shown under the section on the hosted preferences page. Omi
+      #
       # @param has_custom_routing [Boolean, nil] Whether the workspace preference defines custom routing for its topics.
       #
       # @param routing_options [Array<Symbol, Courier::Models::ChannelClassification>, nil] Default channels for the workspace preference. Omit to clear.

data/lib/courier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Courier
-  VERSION = "4.18.2"
+  VERSION = "4.19.0"
 end

data/lib/courier.rb

@@ -80,6 +80,7 @@ require_relative "courier/models/post_tenant_template_publish_request"
 require_relative "courier/models/put_tenant_template_request"
 require_relative "courier/models/users/user_token"
 require_relative "courier/models/workspace_preference_create_request"
+require_relative "courier/models/publish_preferences_request"
 require_relative "courier/models/workspace_preference_replace_request"
 require_relative "courier/models/workspace_preference_topic_create_request"
 require_relative "courier/models/workspace_preference_topic_replace_request"
@@ -371,6 +372,11 @@ require_relative "courier/models/translation_update_params"
 require_relative "courier/models/user_profile"
 require_relative "courier/models/user_profile_firebase_token"
 require_relative "courier/models/user_recipient"
+require_relative "courier/models/users/bulk_preference_topic"
+require_relative "courier/models/users/preference_bulk_replace_params"
+require_relative "courier/models/users/preference_bulk_replace_response"
+require_relative "courier/models/users/preference_bulk_update_params"
+require_relative "courier/models/users/preference_bulk_update_response"
 require_relative "courier/models/users/preference_delete_topic_params"
 require_relative "courier/models/users/preference_retrieve_params"
 require_relative "courier/models/users/preference_retrieve_response"

data/rbi/courier/models/publish_preferences_request.rbi

@@ -0,0 +1,58 @@
+# typed: strong
+
+module Courier
+  module Models
+    class PublishPreferencesRequest < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::PublishPreferencesRequest, Courier::Internal::AnyHash)
+        end
+
+      # Brand for the hosted page - "default" (workspace default brand), "none" (no
+      # brand), or a specific brand id. Defaults to "default".
+      sig { returns(T.nilable(String)) }
+      attr_accessor :brand_id
+
+      # Description shown under the heading on the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
+      # Heading shown at the top of the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :heading
+
+      # Optional page metadata to apply when publishing the workspace's preferences
+      # page. All fields are optional; omitted fields fall back to the page defaults
+      # (and the workspace default brand).
+      sig do
+        params(
+          brand_id: T.nilable(String),
+          description: T.nilable(String),
+          heading: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Brand for the hosted page - "default" (workspace default brand), "none" (no
+        # brand), or a specific brand id. Defaults to "default".
+        brand_id: nil,
+        # Description shown under the heading on the hosted preferences page.
+        description: nil,
+        # Heading shown at the top of the hosted preferences page.
+        heading: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            brand_id: T.nilable(String),
+            description: T.nilable(String),
+            heading: T.nilable(String)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/users/bulk_preference_topic.rbi

@@ -0,0 +1,99 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Users
+      class BulkPreferenceTopic < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Users::BulkPreferenceTopic,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T::Array[Courier::ChannelClassification::TaggedSymbol]) }
+        attr_accessor :custom_routing
+
+        sig { returns(T::Boolean) }
+        attr_accessor :has_custom_routing
+
+        # The applied subscription status. Echoes the requested value, so it is always
+        # OPTED_IN or OPTED_OUT.
+        sig do
+          returns(Courier::Users::BulkPreferenceTopic::Status::TaggedSymbol)
+        end
+        attr_accessor :status
+
+        sig { returns(String) }
+        attr_accessor :topic_id
+
+        # A single topic override echoed in a bulk preference response.
+        sig do
+          params(
+            custom_routing: T::Array[Courier::ChannelClassification::OrSymbol],
+            has_custom_routing: T::Boolean,
+            status: Courier::Users::BulkPreferenceTopic::Status::OrSymbol,
+            topic_id: String
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          custom_routing:,
+          has_custom_routing:,
+          # The applied subscription status. Echoes the requested value, so it is always
+          # OPTED_IN or OPTED_OUT.
+          status:,
+          topic_id:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              custom_routing:
+                T::Array[Courier::ChannelClassification::TaggedSymbol],
+              has_custom_routing: T::Boolean,
+              status: Courier::Users::BulkPreferenceTopic::Status::TaggedSymbol,
+              topic_id: String
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The applied subscription status. Echoes the requested value, so it is always
+        # OPTED_IN or OPTED_OUT.
+        module Status
+          extend Courier::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Courier::Users::BulkPreferenceTopic::Status)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          OPTED_IN =
+            T.let(
+              :OPTED_IN,
+              Courier::Users::BulkPreferenceTopic::Status::TaggedSymbol
+            )
+          OPTED_OUT =
+            T.let(
+              :OPTED_OUT,
+              Courier::Users::BulkPreferenceTopic::Status::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Courier::Users::BulkPreferenceTopic::Status::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/users/preference_bulk_replace_params.rbi

@@ -0,0 +1,188 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Users
+      class PreferenceBulkReplaceParams < Courier::Internal::Type::BaseModel
+        extend Courier::Internal::Type::RequestParameters::Converter
+        include Courier::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Users::PreferenceBulkReplaceParams,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :user_id
+
+        # 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.
+        sig do
+          returns(T::Array[Courier::Users::PreferenceBulkReplaceParams::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::PreferenceBulkReplaceParams::Topic::OrHash
+              ],
+            tenant_id: T.nilable(String),
+            request_options: Courier::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          user_id:,
+          # 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:,
+          # 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::PreferenceBulkReplaceParams::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::PreferenceBulkReplaceParams::Topic,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # The subscription status to apply for this topic.
+          sig do
+            returns(
+              Courier::Users::PreferenceBulkReplaceParams::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::PreferenceBulkReplaceParams::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::PreferenceBulkReplaceParams::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::PreferenceBulkReplaceParams::Topic::Status
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            OPTED_IN =
+              T.let(
+                :OPTED_IN,
+                Courier::Users::PreferenceBulkReplaceParams::Topic::Status::TaggedSymbol
+              )
+            OPTED_OUT =
+              T.let(
+                :OPTED_OUT,
+                Courier::Users::PreferenceBulkReplaceParams::Topic::Status::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  Courier::Users::PreferenceBulkReplaceParams::Topic::Status::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/users/preference_bulk_replace_response.rbi

@@ -0,0 +1,50 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Users
+      class PreferenceBulkReplaceResponse < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Models::Users::PreferenceBulkReplaceResponse,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        # The ids of the overrides that were reset to their topic default.
+        sig { returns(T::Array[String]) }
+        attr_accessor :deleted
+
+        # The complete resulting set of topic overrides for the user.
+        sig { returns(T::Array[Courier::Users::BulkPreferenceTopic]) }
+        attr_accessor :items
+
+        sig do
+          params(
+            deleted: T::Array[String],
+            items: T::Array[Courier::Users::BulkPreferenceTopic::OrHash]
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The ids of the overrides that were reset to their topic default.
+          deleted:,
+          # The complete resulting set of topic overrides for the user.
+          items:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              deleted: T::Array[String],
+              items: T::Array[Courier::Users::BulkPreferenceTopic]
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+    end
+  end
+end