trycourier 4.26.0 → 4.26.2

data/rbi/courier/models/bulk_retrieve_job_response.rbi

@@ -0,0 +1,157 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkRetrieveJobResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Courier::Models::BulkRetrieveJobResponse,
+            Courier::Internal::AnyHash
+          )
+        end
+
+      sig { returns(Courier::Models::BulkRetrieveJobResponse::Job) }
+      attr_reader :job
+
+      sig do
+        params(job: Courier::Models::BulkRetrieveJobResponse::Job::OrHash).void
+      end
+      attr_writer :job
+
+      sig do
+        params(
+          job: Courier::Models::BulkRetrieveJobResponse::Job::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(job:)
+      end
+
+      sig do
+        override.returns({ job: Courier::Models::BulkRetrieveJobResponse::Job })
+      end
+      def to_hash
+      end
+
+      class Job < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Models::BulkRetrieveJobResponse::Job,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        # 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(Courier::InboundBulkMessage) }
+        attr_reader :definition
+
+        sig { params(definition: Courier::InboundBulkMessage::OrHash).void }
+        attr_writer :definition
+
+        sig { returns(Integer) }
+        attr_accessor :enqueued
+
+        sig { returns(Integer) }
+        attr_accessor :failures
+
+        sig { returns(Integer) }
+        attr_accessor :received
+
+        sig do
+          returns(
+            Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+          )
+        end
+        attr_accessor :status
+
+        sig do
+          params(
+            definition: Courier::InboundBulkMessage::OrHash,
+            enqueued: Integer,
+            failures: Integer,
+            received: Integer,
+            status:
+              Courier::Models::BulkRetrieveJobResponse::Job::Status::OrSymbol
+          ).returns(T.attached_class)
+        end
+        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: Courier::InboundBulkMessage,
+              enqueued: Integer,
+              failures: Integer,
+              received: Integer,
+              status:
+                Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Status
+          extend Courier::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Courier::Models::BulkRetrieveJobResponse::Job::Status
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          CREATED =
+            T.let(
+              :CREATED,
+              Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+            )
+          PROCESSING =
+            T.let(
+              :PROCESSING,
+              Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+            )
+          COMPLETED =
+            T.let(
+              :COMPLETED,
+              Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+            )
+          ERROR =
+            T.let(
+              :ERROR,
+              Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Courier::Models::BulkRetrieveJobResponse::Job::Status::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/bulk_run_job_params.rbi

@@ -0,0 +1,35 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkRunJobParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Courier::BulkRunJobParams, Courier::Internal::AnyHash)
+        end
+
+      sig { returns(String) }
+      attr_accessor :job_id
+
+      sig do
+        params(
+          job_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(job_id:, request_options: {})
+      end
+
+      sig do
+        override.returns(
+          { job_id: String, request_options: Courier::RequestOptions }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/inbound_bulk_message.rbi

@@ -0,0 +1,124 @@
+# typed: strong
+
+module Courier
+  module Models
+    class InboundBulkMessage < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::InboundBulkMessage, Courier::Internal::AnyHash)
+        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
+
+      sig { returns(T.nilable(String)) }
+      attr_accessor :brand
+
+      # 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(Courier::ElementalContentSugar, Courier::ElementalContent)
+          )
+        )
+      end
+      attr_accessor :content
+
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_accessor :data
+
+      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
+
+      # 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
+
+      # 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(
+                Courier::ElementalContentSugar::OrHash,
+                Courier::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(Courier::ElementalContentSugar, Courier::ElementalContent)
+              ),
+            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)
+          }
+        )
+      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 Courier::Internal::Type::Union
+
+        Variants =
+          T.type_alias do
+            T.any(Courier::ElementalContentSugar, Courier::ElementalContent)
+          end
+
+        sig do
+          override.returns(
+            T::Array[Courier::InboundBulkMessage::Content::Variants]
+          )
+        end
+        def self.variants
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/inbound_bulk_message_user.rbi

@@ -0,0 +1,88 @@
+# typed: strong
+
+module Courier
+  module Models
+    class InboundBulkMessageUser < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::InboundBulkMessageUser, Courier::Internal::AnyHash)
+        end
+
+      # User-specific data that will be merged with message.data
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :data
+
+      sig { params(data: T.anything).void }
+      attr_writer :data
+
+      sig { returns(T.nilable(Courier::RecipientPreferences)) }
+      attr_reader :preferences
+
+      sig do
+        params(
+          preferences: T.nilable(Courier::RecipientPreferences::OrHash)
+        ).void
+      end
+      attr_writer :preferences
+
+      # 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(Courier::UserRecipient)) }
+      attr_reader :to
+
+      sig { params(to: T.nilable(Courier::UserRecipient::OrHash)).void }
+      attr_writer :to
+
+      sig do
+        params(
+          data: T.anything,
+          preferences: T.nilable(Courier::RecipientPreferences::OrHash),
+          profile: T.nilable(T::Hash[Symbol, T.anything]),
+          recipient: T.nilable(String),
+          to: T.nilable(Courier::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
+
+      sig do
+        override.returns(
+          {
+            data: T.anything,
+            preferences: T.nilable(Courier::RecipientPreferences),
+            profile: T.nilable(T::Hash[Symbol, T.anything]),
+            recipient: T.nilable(String),
+            to: T.nilable(Courier::UserRecipient)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models.rbi

@@ -106,6 +106,16 @@ module Courier
 
   BroadcastUpdateParams = Courier::Models::BroadcastUpdateParams
 
+  BulkAddUsersParams = Courier::Models::BulkAddUsersParams
+
+  BulkCreateJobParams = Courier::Models::BulkCreateJobParams
+
+  BulkListUsersParams = Courier::Models::BulkListUsersParams
+
+  BulkRetrieveJobParams = Courier::Models::BulkRetrieveJobParams
+
+  BulkRunJobParams = Courier::Models::BulkRunJobParams
+
   CancelJourneyRequest = Courier::Models::CancelJourneyRequest
 
   CancelJourneyResponse = Courier::Models::CancelJourneyResponse
@@ -178,6 +188,10 @@ module Courier
 
   Icons = Courier::Models::Icons
 
+  InboundBulkMessage = Courier::Models::InboundBulkMessage
+
+  InboundBulkMessageUser = Courier::Models::InboundBulkMessageUser
+
   InboundTrackEventParams = Courier::Models::InboundTrackEventParams
 
   Intercom = Courier::Models::Intercom

data/rbi/courier/resources/broadcasts.rbi

@@ -31,7 +31,11 @@ module Courier
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Broadcast)
       end
-      def retrieve(broadcast_id, request_options: {})
+      def retrieve(
+        # The broadcast to retrieve, identified by the `id` returned when it was created.
+        broadcast_id,
+        request_options: {}
+      )
       end
 
       # Update a broadcast's name. Content is edited via the broadcast's notification
@@ -44,6 +48,7 @@ module Courier
         ).returns(Courier::Broadcast)
       end
       def update(
+        # The broadcast to rename.
         broadcast_id,
         # New human-readable name.
         name:,
@@ -77,7 +82,11 @@ module Courier
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Broadcast)
       end
-      def archive(broadcast_id, request_options: {})
+      def archive(
+        # The broadcast to archive.
+        broadcast_id,
+        request_options: {}
+      )
       end
 
       # Cancel a broadcast's pending schedule, returning it to the draft state. Only
@@ -88,7 +97,11 @@ module Courier
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Broadcast)
       end
-      def cancel(broadcast_id, request_options: {})
+      def cancel(
+        # The broadcast to cancel.
+        broadcast_id,
+        request_options: {}
+      )
       end
 
       # Duplicate a broadcast (and its template) into a new draft named "{source name}
@@ -99,7 +112,12 @@ module Courier
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Broadcast)
       end
-      def duplicate(broadcast_id, request_options: {})
+      def duplicate(
+        # The broadcast to copy. The duplicate is created as a new draft and this
+        # broadcast is left unchanged.
+        broadcast_id,
+        request_options: {}
+      )
       end
 
       # Author the broadcast's content by replacing the draft elemental content of its
@@ -114,6 +132,7 @@ module Courier
         ).returns(Courier::NotificationContentMutationResponse)
       end
       def put_content(
+        # The broadcast whose content you want to replace.
         broadcast_id,
         # Elemental content payload. The server defaults `version` when omitted.
         content:,
@@ -134,6 +153,7 @@ module Courier
         ).returns(Courier::NotificationContentGetResponse)
       end
       def retrieve_content(
+        # The broadcast whose content you want to read.
         broadcast_id,
         # Accepts `draft`, `published`, or a version string (e.g. `v001`). Defaults to
         # `draft`.
@@ -157,6 +177,7 @@ module Courier
         ).returns(Courier::Broadcast)
       end
       def schedule(
+        # The broadcast to schedule.
         broadcast_id,
         # ID of the target list or audience.
         recipient_id:,
@@ -183,6 +204,7 @@ module Courier
         ).returns(Courier::Broadcast)
       end
       def send_(
+        # The broadcast to send.
         broadcast_id,
         # ID of the target list or audience.
         recipient_id:,

data/rbi/courier/resources/bulk.rbi

@@ -0,0 +1,107 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Bulk
+      # 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,
+          users: T::Array[Courier::InboundBulkMessageUser::OrHash],
+          request_options: Courier::RequestOptions::OrHash
+        ).void
+      end
+      def add_users(
+        # A unique identifier representing the bulk job
+        job_id,
+        users:,
+        request_options: {}
+      )
+      end
+
+      # 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: Courier::InboundBulkMessage::OrHash,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Models::BulkCreateJobResponse)
+      end
+      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
+
+      # Returns the users ingested into a bulk job with paging, each carrying the status
+      # Courier recorded for it and the id of the message it produced.
+      sig do
+        params(
+          job_id: String,
+          cursor: T.nilable(String),
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Models::BulkListUsersResponse)
+      end
+      def list_users(
+        # A unique identifier representing the bulk job
+        job_id,
+        # A unique identifier that allows for fetching the next set of users added to the
+        # bulk job
+        cursor: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns a bulk job's message definition, its status — CREATED, PROCESSING,
+      # COMPLETED, or ERROR — and running counts of users received, messages enqueued,
+      # and failures. Poll it to follow a job through to completion.
+      sig do
+        params(
+          job_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Models::BulkRetrieveJobResponse)
+      end
+      def retrieve_job(
+        # A unique identifier representing the bulk job
+        job_id,
+        request_options: {}
+      )
+      end
+
+      # Starts processing a bulk job, sending to every user ingested into it. Returns
+      # 204 immediately; the job runs asynchronously, so poll the job to watch its
+      # status and counts.
+      sig do
+        params(
+          job_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).void
+      end
+      def run_job(
+        # A unique identifier representing the bulk job
+        job_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Courier::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/courier/resources/send.rbi

@@ -6,7 +6,8 @@ module Courier
     # across every channel you have configured.
     class Send
       # Sends a message to one or more recipients and returns a requestId. Courier
-      # routes it to email, SMS, push, chat, or in-app based on your rules.
+      # routes it to email, SMS, push, chat, or in-app based on your rules. Use the
+      # returned requestId to look up delivery status via the Messages API.
       sig do
         params(
           message: Courier::SendMessageParams::Message::OrHash,

data/sig/courier/client.rbs

@@ -26,6 +26,8 @@ module Courier
 
     attr_reader broadcasts: Courier::Resources::Broadcasts
 
+    attr_reader bulk: Courier::Resources::Bulk
+
     attr_reader brands: Courier::Resources::Brands
 
     attr_reader digests: Courier::Resources::Digests

data/sig/courier/models/bulk_add_users_params.rbs

@@ -0,0 +1,28 @@
+module Courier
+  module Models
+    type bulk_add_users_params =
+      { job_id: String, users: ::Array[Courier::InboundBulkMessageUser] }
+      & Courier::Internal::Type::request_parameters
+
+    class BulkAddUsersParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor job_id: String
+
+      attr_accessor users: ::Array[Courier::InboundBulkMessageUser]
+
+      def initialize: (
+        job_id: String,
+        users: ::Array[Courier::InboundBulkMessageUser],
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        job_id: String,
+        users: ::Array[Courier::InboundBulkMessageUser],
+        request_options: Courier::RequestOptions
+      }
+    end
+  end
+end