trycourier 4.26.0 → 4.26.2

data/lib/courier/resources/bulk.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @overload add_users(job_id, users:, request_options: {})
+      #
+      # @param job_id [String] A unique identifier representing the bulk job
+      #
+      # @param users [Array<Courier::Models::InboundBulkMessageUser>]
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Courier::Models::BulkAddUsersParams
+      def add_users(job_id, params)
+        parsed, options = Courier::BulkAddUsersParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["bulk/%1$s", job_id],
+          body: parsed,
+          model: NilClass,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::BulkCreateJobParams} for more details.
+      #
+      # 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.
+      #
+      # @overload create_job(message:, request_options: {})
+      #
+      # @param message [Courier::Models::InboundBulkMessage] Bulk message definition. Supports two formats:
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::BulkCreateJobResponse]
+      #
+      # @see Courier::Models::BulkCreateJobParams
+      def create_job(params)
+        parsed, options = Courier::BulkCreateJobParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "bulk",
+          body: parsed,
+          model: Courier::Models::BulkCreateJobResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::BulkListUsersParams} for more details.
+      #
+      # 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.
+      #
+      # @overload list_users(job_id, cursor: nil, request_options: {})
+      #
+      # @param job_id [String] A unique identifier representing the bulk job
+      #
+      # @param cursor [String, nil] A unique identifier that allows for fetching the next set of users added to the
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::BulkListUsersResponse]
+      #
+      # @see Courier::Models::BulkListUsersParams
+      def list_users(job_id, params = {})
+        parsed, options = Courier::BulkListUsersParams.dump_request(params)
+        query = Courier::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["bulk/%1$s/users", job_id],
+          query: query,
+          model: Courier::Models::BulkListUsersResponse,
+          options: 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.
+      #
+      # @overload retrieve_job(job_id, request_options: {})
+      #
+      # @param job_id [String] A unique identifier representing the bulk job
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::BulkRetrieveJobResponse]
+      #
+      # @see Courier::Models::BulkRetrieveJobParams
+      def retrieve_job(job_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["bulk/%1$s", job_id],
+          model: Courier::Models::BulkRetrieveJobResponse,
+          options: params[: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.
+      #
+      # @overload run_job(job_id, request_options: {})
+      #
+      # @param job_id [String] A unique identifier representing the bulk job
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [nil]
+      #
+      # @see Courier::Models::BulkRunJobParams
+      def run_job(job_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["bulk/%1$s/run", job_id],
+          model: NilClass,
+          options: params[:request_options]
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Courier::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/courier/resources/send.rb

@@ -9,7 +9,8 @@ module Courier
       # {Courier::Models::SendMessageParams} for more details.
       #
       # 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.
       #
       # @overload message(message:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #

data/lib/courier/version.rb

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

data/lib/courier.rb

@@ -59,6 +59,7 @@ require_relative "courier/models/notification_content_put_request"
 require_relative "courier/models/schedule_broadcast_request"
 require_relative "courier/models/send_broadcast_request"
 require_relative "courier/models/update_broadcast_request"
+require_relative "courier/models/inbound_bulk_message_user"
 require_relative "courier/models/base_check"
 require_relative "courier/models/subscription_topic_new"
 require_relative "courier/models/elemental_channel_node"
@@ -142,6 +143,14 @@ require_relative "courier/models/broadcast_schedule"
 require_relative "courier/models/broadcast_schedule_params"
 require_relative "courier/models/broadcast_send_params"
 require_relative "courier/models/broadcast_update_params"
+require_relative "courier/models/bulk_add_users_params"
+require_relative "courier/models/bulk_create_job_params"
+require_relative "courier/models/bulk_create_job_response"
+require_relative "courier/models/bulk_list_users_params"
+require_relative "courier/models/bulk_list_users_response"
+require_relative "courier/models/bulk_retrieve_job_params"
+require_relative "courier/models/bulk_retrieve_job_response"
+require_relative "courier/models/bulk_run_job_params"
 require_relative "courier/models/cancel_journey_response"
 require_relative "courier/models/channel"
 require_relative "courier/models/channel_classification"
@@ -174,6 +183,7 @@ require_relative "courier/models/email_header"
 require_relative "courier/models/expo"
 require_relative "courier/models/filter_config"
 require_relative "courier/models/icons"
+require_relative "courier/models/inbound_bulk_message"
 require_relative "courier/models/inbound_track_event_params"
 require_relative "courier/models/inbound_track_event_response"
 require_relative "courier/models/intercom"
@@ -442,6 +452,7 @@ require_relative "courier/resources/automations"
 require_relative "courier/resources/automations/invoke"
 require_relative "courier/resources/brands"
 require_relative "courier/resources/broadcasts"
+require_relative "courier/resources/bulk"
 require_relative "courier/resources/digests"
 require_relative "courier/resources/digests/schedules"
 require_relative "courier/resources/inbound"

data/rbi/courier/client.rbi

@@ -53,6 +53,9 @@ module Courier
     sig { returns(Courier::Resources::Broadcasts) }
     attr_reader :broadcasts
 
+    sig { returns(Courier::Resources::Bulk) }
+    attr_reader :bulk
+
     # Manage the logos, colors, and layout that give the templates you send a
     # consistent look.
     sig { returns(Courier::Resources::Brands) }

data/rbi/courier/models/bulk_add_users_params.rbi

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

data/rbi/courier/models/bulk_create_job_params.rbi

@@ -0,0 +1,54 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkCreateJobParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Courier::BulkCreateJobParams, 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 :message
+
+      sig { params(message: Courier::InboundBulkMessage::OrHash).void }
+      attr_writer :message
+
+      sig do
+        params(
+          message: Courier::InboundBulkMessage::OrHash,
+          request_options: Courier::RequestOptions::OrHash
+        ).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`
+        message:,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            message: Courier::InboundBulkMessage,
+            request_options: Courier::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/bulk_create_job_response.rbi

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

data/rbi/courier/models/bulk_list_users_params.rbi

@@ -0,0 +1,51 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkListUsersParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Courier::BulkListUsersParams, Courier::Internal::AnyHash)
+        end
+
+      sig { returns(String) }
+      attr_accessor :job_id
+
+      # A unique identifier that allows for fetching the next set of users added to the
+      # bulk job
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cursor
+
+      sig do
+        params(
+          job_id: String,
+          cursor: T.nilable(String),
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        job_id:,
+        # A unique identifier that allows for fetching the next set of users added to the
+        # bulk job
+        cursor: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            job_id: String,
+            cursor: T.nilable(String),
+            request_options: Courier::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/bulk_list_users_response.rbi

@@ -0,0 +1,125 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkListUsersResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Courier::Models::BulkListUsersResponse,
+            Courier::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T::Array[Courier::Models::BulkListUsersResponse::Item]) }
+      attr_accessor :items
+
+      sig { returns(Courier::Paging) }
+      attr_reader :paging
+
+      sig { params(paging: Courier::Paging::OrHash).void }
+      attr_writer :paging
+
+      sig do
+        params(
+          items: T::Array[Courier::Models::BulkListUsersResponse::Item::OrHash],
+          paging: Courier::Paging::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(items:, paging:)
+      end
+
+      sig do
+        override.returns(
+          {
+            items: T::Array[Courier::Models::BulkListUsersResponse::Item],
+            paging: Courier::Paging
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Item < Courier::Models::InboundBulkMessageUser
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Models::BulkListUsersResponse::Item,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        sig do
+          returns(
+            Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol
+          )
+        end
+        attr_accessor :status
+
+        sig { returns(T.nilable(String)) }
+        attr_accessor :message_id
+
+        sig do
+          params(
+            status:
+              Courier::Models::BulkListUsersResponse::Item::Status::OrSymbol,
+            message_id: T.nilable(String)
+          ).returns(T.attached_class)
+        end
+        def self.new(status:, message_id: nil)
+        end
+
+        sig do
+          override.returns(
+            {
+              status:
+                Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol,
+              message_id: T.nilable(String)
+            }
+          )
+        end
+        def to_hash
+        end
+
+        module Status
+          extend Courier::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Courier::Models::BulkListUsersResponse::Item::Status
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          PENDING =
+            T.let(
+              :PENDING,
+              Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol
+            )
+          ENQUEUED =
+            T.let(
+              :ENQUEUED,
+              Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol
+            )
+          ERROR =
+            T.let(
+              :ERROR,
+              Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Courier::Models::BulkListUsersResponse::Item::Status::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/bulk_retrieve_job_params.rbi

@@ -0,0 +1,35 @@
+# typed: strong
+
+module Courier
+  module Models
+    class BulkRetrieveJobParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(Courier::BulkRetrieveJobParams, 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