trycourier 4.3.0 → 4.4.0

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/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/resources/bulk.rbi

@@ -3,7 +3,11 @@
 module Trycourier
   module Resources
     class Bulk
-      # Ingest user data into a Bulk Job
+      # Ingest user data into a Bulk Job.
+      #
+      # **Important**: For email-based bulk jobs, each user must include `profile.email`
+      # for provider routing to work correctly. The `to.email` field is not sufficient
+      # for email provider routing.
       sig do
         params(
           job_id: String,
@@ -19,18 +23,28 @@ module Trycourier
       )
       end
 
-      # Create a bulk job
+      # Creates a new bulk job for sending messages to multiple recipients.
+      #
+      # **Required**: `message.event` (event ID or notification ID)
+      #
+      # **Optional (V2 format)**: `message.template` (notification ID) or
+      # `message.content` (Elemental content) can be provided to override the
+      # notification associated with the event.
       sig do
         params(
-          message:
-            T.any(
-              Trycourier::InboundBulkMessage::InboundBulkTemplateMessage::OrHash,
-              Trycourier::InboundBulkMessage::InboundBulkContentMessage::OrHash
-            ),
+          message: Trycourier::InboundBulkMessage::OrHash,
           request_options: Trycourier::RequestOptions::OrHash
         ).returns(Trycourier::Models::BulkCreateJobResponse)
       end
-      def create_job(message:, request_options: {})
+      def create_job(
+        # 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
 
       # Get Bulk Job Users

data/sig/trycourier/models/bulk_create_job_params.rbs

@@ -1,22 +1,22 @@
 module Trycourier
   module Models
     type bulk_create_job_params =
-      { message: Trycourier::Models::inbound_bulk_message }
+      { message: Trycourier::InboundBulkMessage }
       & Trycourier::Internal::Type::request_parameters
 
     class BulkCreateJobParams < Trycourier::Internal::Type::BaseModel
       extend Trycourier::Internal::Type::RequestParameters::Converter
       include Trycourier::Internal::Type::RequestParameters
 
-      attr_accessor message: Trycourier::Models::inbound_bulk_message
+      attr_accessor message: Trycourier::InboundBulkMessage
 
       def initialize: (
-        message: Trycourier::Models::inbound_bulk_message,
+        message: Trycourier::InboundBulkMessage,
         ?request_options: Trycourier::request_opts
       ) -> void
 
       def to_hash: -> {
-        message: Trycourier::Models::inbound_bulk_message,
+        message: Trycourier::InboundBulkMessage,
         request_options: Trycourier::RequestOptions
       }
     end

data/sig/trycourier/models/bulk_retrieve_job_response.rbs

@@ -14,7 +14,7 @@ module Trycourier
 
       type job =
         {
-          definition: Trycourier::Models::inbound_bulk_message,
+          definition: Trycourier::InboundBulkMessage,
           enqueued: Integer,
           failures: Integer,
           received: Integer,
@@ -22,7 +22,7 @@ module Trycourier
         }
 
       class Job < Trycourier::Internal::Type::BaseModel
-        attr_accessor definition: Trycourier::Models::inbound_bulk_message
+        attr_accessor definition: Trycourier::InboundBulkMessage
 
         attr_accessor enqueued: Integer
 
@@ -33,7 +33,7 @@ module Trycourier
         attr_accessor status: Trycourier::Models::BulkRetrieveJobResponse::Job::status
 
         def initialize: (
-          definition: Trycourier::Models::inbound_bulk_message,
+          definition: Trycourier::InboundBulkMessage,
           enqueued: Integer,
           failures: Integer,
           received: Integer,
@@ -41,7 +41,7 @@ module Trycourier
         ) -> void
 
         def to_hash: -> {
-          definition: Trycourier::Models::inbound_bulk_message,
+          definition: Trycourier::InboundBulkMessage,
           enqueued: Integer,
           failures: Integer,
           received: Integer,

data/sig/trycourier/models/inbound_bulk_message.rbs

@@ -1,106 +1,59 @@
 module Trycourier
   module Models
     type inbound_bulk_message =
-      Trycourier::InboundBulkMessage::InboundBulkTemplateMessage
-      | Trycourier::InboundBulkMessage::InboundBulkContentMessage
-
-    module InboundBulkMessage
-      extend Trycourier::Internal::Type::Union
-
-      type inbound_bulk_template_message =
-        {
-          template: String,
-          brand: String?,
-          data: ::Hash[Symbol, top]?,
-          event: String?,
-          locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          override: ::Hash[Symbol, top]?
-        }
-
-      class InboundBulkTemplateMessage < Trycourier::Internal::Type::BaseModel
-        attr_accessor template: String
-
-        attr_accessor brand: String?
-
-        attr_accessor data: ::Hash[Symbol, top]?
-
-        attr_accessor event: String?
-
-        attr_accessor locale: ::Hash[Symbol, ::Hash[Symbol, top]]?
-
-        attr_accessor override: ::Hash[Symbol, top]?
-
-        def initialize: (
-          template: String,
-          ?brand: String?,
-          ?data: ::Hash[Symbol, top]?,
-          ?event: String?,
-          ?locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          ?override: ::Hash[Symbol, top]?
-        ) -> void
-
-        def to_hash: -> {
-          template: String,
-          brand: String?,
-          data: ::Hash[Symbol, top]?,
-          event: String?,
-          locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          override: ::Hash[Symbol, top]?
-        }
-      end
-
-      type inbound_bulk_content_message =
-        {
-          content: Trycourier::Models::InboundBulkMessage::InboundBulkContentMessage::content,
-          brand: String?,
-          data: ::Hash[Symbol, top]?,
-          event: String?,
-          locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          override: ::Hash[Symbol, top]?
-        }
-
-      class InboundBulkContentMessage < Trycourier::Internal::Type::BaseModel
-        attr_accessor content: Trycourier::Models::InboundBulkMessage::InboundBulkContentMessage::content
-
-        attr_accessor brand: String?
-
-        attr_accessor data: ::Hash[Symbol, top]?
-
-        attr_accessor event: String?
-
-        attr_accessor locale: ::Hash[Symbol, ::Hash[Symbol, top]]?
-
-        attr_accessor override: ::Hash[Symbol, top]?
-
-        def initialize: (
-          content: Trycourier::Models::InboundBulkMessage::InboundBulkContentMessage::content,
-          ?brand: String?,
-          ?data: ::Hash[Symbol, top]?,
-          ?event: String?,
-          ?locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          ?override: ::Hash[Symbol, top]?
-        ) -> void
-
-        def to_hash: -> {
-          content: Trycourier::Models::InboundBulkMessage::InboundBulkContentMessage::content,
-          brand: String?,
-          data: ::Hash[Symbol, top]?,
-          event: String?,
-          locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
-          override: ::Hash[Symbol, top]?
-        }
-
-        type content =
-          Trycourier::ElementalContentSugar | Trycourier::ElementalContent
-
-        module Content
-          extend Trycourier::Internal::Type::Union
-
-          def self?.variants: -> ::Array[Trycourier::Models::InboundBulkMessage::InboundBulkContentMessage::content]
-        end
+      {
+        event: String,
+        brand: String?,
+        content: Trycourier::Models::InboundBulkMessage::content?,
+        data: ::Hash[Symbol, top]?,
+        locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
+        override: ::Hash[Symbol, top]?,
+        template: String?
+      }
+
+    class InboundBulkMessage < Trycourier::Internal::Type::BaseModel
+      attr_accessor event: String
+
+      attr_accessor brand: String?
+
+      attr_accessor content: Trycourier::Models::InboundBulkMessage::content?
+
+      attr_accessor data: ::Hash[Symbol, top]?
+
+      attr_accessor locale: ::Hash[Symbol, ::Hash[Symbol, top]]?
+
+      attr_accessor override: ::Hash[Symbol, top]?
+
+      attr_accessor template: String?
+
+      def initialize: (
+        event: String,
+        ?brand: String?,
+        ?content: Trycourier::Models::InboundBulkMessage::content?,
+        ?data: ::Hash[Symbol, top]?,
+        ?locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
+        ?override: ::Hash[Symbol, top]?,
+        ?template: String?
+      ) -> void
+
+      def to_hash: -> {
+        event: String,
+        brand: String?,
+        content: Trycourier::Models::InboundBulkMessage::content?,
+        data: ::Hash[Symbol, top]?,
+        locale: ::Hash[Symbol, ::Hash[Symbol, top]]?,
+        override: ::Hash[Symbol, top]?,
+        template: String?
+      }
+
+      type content =
+        Trycourier::ElementalContentSugar | Trycourier::ElementalContent
+
+      module Content
+        extend Trycourier::Internal::Type::Union
+
+        def self?.variants: -> ::Array[Trycourier::Models::InboundBulkMessage::content]
       end
-
-      def self?.variants: -> ::Array[Trycourier::Models::inbound_bulk_message]
     end
   end
 end