trycourier 4.2.0 → 4.4.0

data/rbi/trycourier/models/bulk_create_job_params.rbi

@@ -11,37 +11,38 @@ module Trycourier
           T.any(Trycourier::BulkCreateJobParams, Trycourier::Internal::AnyHash)
         end
 
-      sig do
-        returns(
-          T.any(
-            Trycourier::InboundBulkMessage::InboundBulkTemplateMessage,
-            Trycourier::InboundBulkMessage::InboundBulkContentMessage
-          )
-        )
-      end
-      attr_accessor :message
+      # Bulk message definition. Supports two formats:
+      #
+      # - V1 format: Requires `event` field (event ID or notification ID)
+      # - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+      #   content) in addition to `event`
+      sig { returns(Trycourier::InboundBulkMessage) }
+      attr_reader :message
+
+      sig { params(message: Trycourier::InboundBulkMessage::OrHash).void }
+      attr_writer :message
 
       sig do
         params(
-          message:
-            T.any(
-              Trycourier::InboundBulkMessage::InboundBulkTemplateMessage::OrHash,
-              Trycourier::InboundBulkMessage::InboundBulkContentMessage::OrHash
-            ),
+          message: Trycourier::InboundBulkMessage::OrHash,
           request_options: Trycourier::RequestOptions::OrHash
         ).returns(T.attached_class)
       end
-      def self.new(message:, request_options: {})
+      def self.new(
+        # Bulk message definition. Supports two formats:
+        #
+        # - V1 format: Requires `event` field (event ID or notification ID)
+        # - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+        #   content) in addition to `event`
+        message:,
+        request_options: {}
+      )
       end
 
       sig do
         override.returns(
           {
-            message:
-              T.any(
-                Trycourier::InboundBulkMessage::InboundBulkTemplateMessage,
-                Trycourier::InboundBulkMessage::InboundBulkContentMessage
-              ),
+            message: Trycourier::InboundBulkMessage,
             request_options: Trycourier::RequestOptions
           }
         )

data/rbi/trycourier/models/bulk_retrieve_job_response.rbi

@@ -46,8 +46,16 @@ module Trycourier
             )
           end
 
-        sig { returns(Trycourier::InboundBulkMessage::Variants) }
-        attr_accessor :definition
+        # Bulk message definition. Supports two formats:
+        #
+        # - V1 format: Requires `event` field (event ID or notification ID)
+        # - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+        #   content) in addition to `event`
+        sig { returns(Trycourier::InboundBulkMessage) }
+        attr_reader :definition
+
+        sig { params(definition: Trycourier::InboundBulkMessage::OrHash).void }
+        attr_writer :definition
 
         sig { returns(Integer) }
         attr_accessor :enqueued
@@ -67,11 +75,7 @@ module Trycourier
 
         sig do
           params(
-            definition:
-              T.any(
-                Trycourier::InboundBulkMessage::InboundBulkTemplateMessage::OrHash,
-                Trycourier::InboundBulkMessage::InboundBulkContentMessage::OrHash
-              ),
+            definition: Trycourier::InboundBulkMessage::OrHash,
             enqueued: Integer,
             failures: Integer,
             received: Integer,
@@ -79,13 +83,24 @@ module Trycourier
               Trycourier::Models::BulkRetrieveJobResponse::Job::Status::OrSymbol
           ).returns(T.attached_class)
         end
-        def self.new(definition:, enqueued:, failures:, received:, status:)
+        def self.new(
+          # Bulk message definition. Supports two formats:
+          #
+          # - V1 format: Requires `event` field (event ID or notification ID)
+          # - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+          #   content) in addition to `event`
+          definition:,
+          enqueued:,
+          failures:,
+          received:,
+          status:
+        )
         end
 
         sig do
           override.returns(
             {
-              definition: Trycourier::InboundBulkMessage::Variants,
+              definition: Trycourier::InboundBulkMessage,
               enqueued: Integer,
               failures: Integer,
               received: Integer,

data/rbi/trycourier/models/inbound_bulk_message.rbi

@@ -2,187 +2,131 @@
 
 module Trycourier
   module Models
-    module InboundBulkMessage
-      extend Trycourier::Internal::Type::Union
-
-      Variants =
+    class InboundBulkMessage < Trycourier::Internal::Type::BaseModel
+      OrHash =
         T.type_alias do
-          T.any(
-            Trycourier::InboundBulkMessage::InboundBulkTemplateMessage,
-            Trycourier::InboundBulkMessage::InboundBulkContentMessage
-          )
-        end
-
-      class InboundBulkTemplateMessage < Trycourier::Internal::Type::BaseModel
-        OrHash =
-          T.type_alias do
-            T.any(
-              Trycourier::InboundBulkMessage::InboundBulkTemplateMessage,
-              Trycourier::Internal::AnyHash
-            )
-          end
-
-        sig { returns(String) }
-        attr_accessor :template
-
-        sig { returns(T.nilable(String)) }
-        attr_accessor :brand
-
-        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-        attr_accessor :data
-
-        sig { returns(T.nilable(String)) }
-        attr_accessor :event
-
-        sig { returns(T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]])) }
-        attr_accessor :locale
-
-        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-        attr_accessor :override
-
-        sig do
-          params(
-            template: String,
-            brand: T.nilable(String),
-            data: T.nilable(T::Hash[Symbol, T.anything]),
-            event: T.nilable(String),
-            locale: T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]]),
-            override: T.nilable(T::Hash[Symbol, T.anything])
-          ).returns(T.attached_class)
-        end
-        def self.new(
-          template:,
-          brand: nil,
-          data: nil,
-          event: nil,
-          locale: nil,
-          override: nil
-        )
+          T.any(Trycourier::InboundBulkMessage, Trycourier::Internal::AnyHash)
         end
 
-        sig do
-          override.returns(
-            {
-              template: String,
-              brand: T.nilable(String),
-              data: T.nilable(T::Hash[Symbol, T.anything]),
-              event: T.nilable(String),
-              locale: T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]]),
-              override: T.nilable(T::Hash[Symbol, T.anything])
-            }
-          )
-        end
-        def to_hash
-        end
-      end
+      # Event ID or Notification ID (required). Can be either a Notification ID (e.g.,
+      # "FRH3QXM9E34W4RKP7MRC8NZ1T8V8") or a custom Event ID (e.g., "welcome-email")
+      # mapped to a notification.
+      sig { returns(String) }
+      attr_accessor :event
 
-      class InboundBulkContentMessage < Trycourier::Internal::Type::BaseModel
-        OrHash =
-          T.type_alias do
-            T.any(
-              Trycourier::InboundBulkMessage::InboundBulkContentMessage,
-              Trycourier::Internal::AnyHash
-            )
-          end
+      sig { returns(T.nilable(String)) }
+      attr_accessor :brand
 
-        # Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks.
-        sig do
-          returns(
+      # Elemental content (optional, for V2 format). When provided, this will be used
+      # instead of the notification associated with the `event` field.
+      sig do
+        returns(
+          T.nilable(
             T.any(
               Trycourier::ElementalContentSugar,
               Trycourier::ElementalContent
             )
           )
-        end
-        attr_accessor :content
-
-        sig { returns(T.nilable(String)) }
-        attr_accessor :brand
+        )
+      end
+      attr_accessor :content
 
-        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-        attr_accessor :data
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :data
 
-        sig { returns(T.nilable(String)) }
-        attr_accessor :event
+      sig { returns(T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]])) }
+      attr_accessor :locale
 
-        sig { returns(T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]])) }
-        attr_accessor :locale
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :override
 
-        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
-        attr_accessor :override
+      # Notification ID or template ID (optional, for V2 format). When provided, this
+      # will be used instead of the notification associated with the `event` field.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :template
 
-        sig do
-          params(
-            content:
+      # Bulk message definition. Supports two formats:
+      #
+      # - V1 format: Requires `event` field (event ID or notification ID)
+      # - V2 format: Optionally use `template` (notification ID) or `content` (Elemental
+      #   content) in addition to `event`
+      sig do
+        params(
+          event: String,
+          brand: T.nilable(String),
+          content:
+            T.nilable(
               T.any(
                 Trycourier::ElementalContentSugar::OrHash,
                 Trycourier::ElementalContent::OrHash
-              ),
+              )
+            ),
+          data: T.nilable(T::Hash[Symbol, T.anything]),
+          locale: T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]]),
+          override: T.nilable(T::Hash[Symbol, T.anything]),
+          template: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Event ID or Notification ID (required). Can be either a Notification ID (e.g.,
+        # "FRH3QXM9E34W4RKP7MRC8NZ1T8V8") or a custom Event ID (e.g., "welcome-email")
+        # mapped to a notification.
+        event:,
+        brand: nil,
+        # Elemental content (optional, for V2 format). When provided, this will be used
+        # instead of the notification associated with the `event` field.
+        content: nil,
+        data: nil,
+        locale: nil,
+        override: nil,
+        # Notification ID or template ID (optional, for V2 format). When provided, this
+        # will be used instead of the notification associated with the `event` field.
+        template: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            event: String,
             brand: T.nilable(String),
+            content:
+              T.nilable(
+                T.any(
+                  Trycourier::ElementalContentSugar,
+                  Trycourier::ElementalContent
+                )
+              ),
             data: T.nilable(T::Hash[Symbol, T.anything]),
-            event: T.nilable(String),
             locale: T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]]),
-            override: T.nilable(T::Hash[Symbol, T.anything])
-          ).returns(T.attached_class)
-        end
-        def self.new(
-          # Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks.
-          content:,
-          brand: nil,
-          data: nil,
-          event: nil,
-          locale: nil,
-          override: nil
+            override: T.nilable(T::Hash[Symbol, T.anything]),
+            template: T.nilable(String)
+          }
         )
-        end
+      end
+      def to_hash
+      end
+
+      # Elemental content (optional, for V2 format). When provided, this will be used
+      # instead of the notification associated with the `event` field.
+      module Content
+        extend Trycourier::Internal::Type::Union
+
+        Variants =
+          T.type_alias do
+            T.any(
+              Trycourier::ElementalContentSugar,
+              Trycourier::ElementalContent
+            )
+          end
 
         sig do
           override.returns(
-            {
-              content:
-                T.any(
-                  Trycourier::ElementalContentSugar,
-                  Trycourier::ElementalContent
-                ),
-              brand: T.nilable(String),
-              data: T.nilable(T::Hash[Symbol, T.anything]),
-              event: T.nilable(String),
-              locale: T.nilable(T::Hash[Symbol, T::Hash[Symbol, T.anything]]),
-              override: T.nilable(T::Hash[Symbol, T.anything])
-            }
+            T::Array[Trycourier::InboundBulkMessage::Content::Variants]
           )
         end
-        def to_hash
+        def self.variants
         end
-
-        # Syntactic sugar to provide a fast shorthand for Courier Elemental Blocks.
-        module Content
-          extend Trycourier::Internal::Type::Union
-
-          Variants =
-            T.type_alias do
-              T.any(
-                Trycourier::ElementalContentSugar,
-                Trycourier::ElementalContent
-              )
-            end
-
-          sig do
-            override.returns(
-              T::Array[
-                Trycourier::InboundBulkMessage::InboundBulkContentMessage::Content::Variants
-              ]
-            )
-          end
-          def self.variants
-          end
-        end
-      end
-
-      sig do
-        override.returns(T::Array[Trycourier::InboundBulkMessage::Variants])
-      end
-      def self.variants
       end
     end
   end

data/rbi/trycourier/models/inbound_bulk_message_user.rbi

@@ -11,6 +11,7 @@ module Trycourier
           )
         end
 
+      # User-specific data that will be merged with message.data
       sig { returns(T.nilable(T.anything)) }
       attr_reader :data
 
@@ -27,15 +28,19 @@ module Trycourier
       end
       attr_writer :preferences
 
-      sig { returns(T.nilable(T.anything)) }
-      attr_reader :profile
-
-      sig { params(profile: T.anything).void }
-      attr_writer :profile
+      # User profile information. For email-based bulk jobs, `profile.email` is required
+      # for provider routing to determine if the message can be delivered. The email
+      # address should be provided here rather than in `to.email`.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :profile
 
+      # User ID (legacy field, use profile or to.user_id instead)
       sig { returns(T.nilable(String)) }
       attr_accessor :recipient
 
+      # Optional recipient information. Note: For email provider routing, use
+      # `profile.email` instead of `to.email`. The `to` field is primarily used for
+      # recipient identification and data merging.
       sig { returns(T.nilable(Trycourier::UserRecipient)) }
       attr_reader :to
 
@@ -46,16 +51,24 @@ module Trycourier
         params(
           data: T.anything,
           preferences: T.nilable(Trycourier::RecipientPreferences::OrHash),
-          profile: T.anything,
+          profile: T.nilable(T::Hash[Symbol, T.anything]),
           recipient: T.nilable(String),
           to: T.nilable(Trycourier::UserRecipient::OrHash)
         ).returns(T.attached_class)
       end
       def self.new(
+        # User-specific data that will be merged with message.data
         data: nil,
         preferences: nil,
+        # User profile information. For email-based bulk jobs, `profile.email` is required
+        # for provider routing to determine if the message can be delivered. The email
+        # address should be provided here rather than in `to.email`.
         profile: nil,
+        # User ID (legacy field, use profile or to.user_id instead)
         recipient: nil,
+        # Optional recipient information. Note: For email provider routing, use
+        # `profile.email` instead of `to.email`. The `to` field is primarily used for
+        # recipient identification and data merging.
         to: nil
       )
       end
@@ -65,7 +78,7 @@ module Trycourier
           {
             data: T.anything,
             preferences: T.nilable(Trycourier::RecipientPreferences),
-            profile: T.anything,
+            profile: T.nilable(T::Hash[Symbol, T.anything]),
             recipient: T.nilable(String),
             to: T.nilable(Trycourier::UserRecipient)
           }

data/rbi/trycourier/models/recipient.rbi

@@ -40,12 +40,12 @@ module Trycourier
       sig { returns(T.nilable(String)) }
       attr_accessor :phone_number
 
-      sig { returns(T.nilable(Trycourier::ProfilePreferences)) }
+      sig { returns(T.nilable(Trycourier::Recipient::Preferences)) }
       attr_reader :preferences
 
       sig do
         params(
-          preferences: T.nilable(Trycourier::ProfilePreferences::OrHash)
+          preferences: T.nilable(Trycourier::Recipient::Preferences::OrHash)
         ).void
       end
       attr_writer :preferences
@@ -68,7 +68,7 @@ module Trycourier
           list_id: T.nilable(String),
           locale: T.nilable(String),
           phone_number: T.nilable(String),
-          preferences: T.nilable(Trycourier::ProfilePreferences::OrHash),
+          preferences: T.nilable(Trycourier::Recipient::Preferences::OrHash),
           tenant_id: T.nilable(String),
           user_id: T.nilable(String)
         ).returns(T.attached_class)
@@ -106,7 +106,7 @@ module Trycourier
             list_id: T.nilable(String),
             locale: T.nilable(String),
             phone_number: T.nilable(String),
-            preferences: T.nilable(Trycourier::ProfilePreferences),
+            preferences: T.nilable(Trycourier::Recipient::Preferences),
             tenant_id: T.nilable(String),
             user_id: T.nilable(String)
           }
@@ -114,6 +114,48 @@ module Trycourier
       end
       def to_hash
       end
+
+      class Preferences < Trycourier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Trycourier::Recipient::Preferences,
+              Trycourier::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T::Hash[Symbol, Trycourier::Preference]) }
+        attr_accessor :notifications
+
+        sig { returns(T.nilable(T::Hash[Symbol, Trycourier::Preference])) }
+        attr_accessor :categories
+
+        sig { returns(T.nilable(String)) }
+        attr_accessor :template_id
+
+        sig do
+          params(
+            notifications: T::Hash[Symbol, Trycourier::Preference::OrHash],
+            categories:
+              T.nilable(T::Hash[Symbol, Trycourier::Preference::OrHash]),
+            template_id: T.nilable(String)
+          ).returns(T.attached_class)
+        end
+        def self.new(notifications:, categories: nil, template_id: nil)
+        end
+
+        sig do
+          override.returns(
+            {
+              notifications: T::Hash[Symbol, Trycourier::Preference],
+              categories: T.nilable(T::Hash[Symbol, Trycourier::Preference]),
+              template_id: T.nilable(String)
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/trycourier/models/send_message_params.rbi

@@ -609,6 +609,12 @@ module Trycourier
           sig { returns(T.nilable(Integer)) }
           attr_accessor :duration
 
+          # IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Used when
+          # resolving opening hours expressions. Takes precedence over user profile timezone
+          # settings.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :timezone
+
           # ISO 8601 timestamp or opening_hours-like format.
           sig { returns(T.nilable(String)) }
           attr_accessor :until_
@@ -616,12 +622,17 @@ module Trycourier
           sig do
             params(
               duration: T.nilable(Integer),
+              timezone: T.nilable(String),
               until_: T.nilable(String)
             ).returns(T.attached_class)
           end
           def self.new(
             # The duration of the delay in milliseconds.
             duration: nil,
+            # IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Used when
+            # resolving opening hours expressions. Takes precedence over user profile timezone
+            # settings.
+            timezone: nil,
             # ISO 8601 timestamp or opening_hours-like format.
             until_: nil
           )
@@ -629,7 +640,11 @@ module Trycourier
 
           sig do
             override.returns(
-              { duration: T.nilable(Integer), until_: T.nilable(String) }
+              {
+                duration: T.nilable(Integer),
+                timezone: T.nilable(String),
+                until_: T.nilable(String)
+              }
             )
           end
           def to_hash

data/rbi/trycourier/models/user_recipient.rbi

@@ -40,12 +40,12 @@ module Trycourier
       sig { returns(T.nilable(String)) }
       attr_accessor :phone_number
 
-      sig { returns(T.nilable(Trycourier::ProfilePreferences)) }
+      sig { returns(T.nilable(Trycourier::UserRecipient::Preferences)) }
       attr_reader :preferences
 
       sig do
         params(
-          preferences: T.nilable(Trycourier::ProfilePreferences::OrHash)
+          preferences: T.nilable(Trycourier::UserRecipient::Preferences::OrHash)
         ).void
       end
       attr_writer :preferences
@@ -68,7 +68,8 @@ module Trycourier
           list_id: T.nilable(String),
           locale: T.nilable(String),
           phone_number: T.nilable(String),
-          preferences: T.nilable(Trycourier::ProfilePreferences::OrHash),
+          preferences:
+            T.nilable(Trycourier::UserRecipient::Preferences::OrHash),
           tenant_id: T.nilable(String),
           user_id: T.nilable(String)
         ).returns(T.attached_class)
@@ -106,7 +107,7 @@ module Trycourier
             list_id: T.nilable(String),
             locale: T.nilable(String),
             phone_number: T.nilable(String),
-            preferences: T.nilable(Trycourier::ProfilePreferences),
+            preferences: T.nilable(Trycourier::UserRecipient::Preferences),
             tenant_id: T.nilable(String),
             user_id: T.nilable(String)
           }
@@ -114,6 +115,48 @@ module Trycourier
       end
       def to_hash
       end
+
+      class Preferences < Trycourier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Trycourier::UserRecipient::Preferences,
+              Trycourier::Internal::AnyHash
+            )
+          end
+
+        sig { returns(T::Hash[Symbol, Trycourier::Preference]) }
+        attr_accessor :notifications
+
+        sig { returns(T.nilable(T::Hash[Symbol, Trycourier::Preference])) }
+        attr_accessor :categories
+
+        sig { returns(T.nilable(String)) }
+        attr_accessor :template_id
+
+        sig do
+          params(
+            notifications: T::Hash[Symbol, Trycourier::Preference::OrHash],
+            categories:
+              T.nilable(T::Hash[Symbol, Trycourier::Preference::OrHash]),
+            template_id: T.nilable(String)
+          ).returns(T.attached_class)
+        end
+        def self.new(notifications:, categories: nil, template_id: nil)
+        end
+
+        sig do
+          override.returns(
+            {
+              notifications: T::Hash[Symbol, Trycourier::Preference],
+              categories: T.nilable(T::Hash[Symbol, Trycourier::Preference]),
+              template_id: T.nilable(String)
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end