trycourier 6.10.0 → 6.11.0

data/lib/courier/resources/previews.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Courier
+  module Resources
+    # Render a template's email content on real email clients and read back the
+    # screenshots, so you can check how it looks before you send it.
+    class Previews
+      # Archive a device set. This is a soft delete — the archived set is returned and
+      # no longer appears in list results. Runs already created against it keep their
+      # own copy of the device list and are unaffected. The Courier-provided default set
+      # cannot be archived and returns 409.
+      #
+      # @overload archive_device_set(device_set_id, request_options: {})
+      #
+      # @param device_set_id [String] The preview set to archive.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::DeviceSet]
+      #
+      # @see Courier::Models::PreviewArchiveDeviceSetParams
+      def archive_device_set(device_set_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["previews/device-sets/%1$s", device_set_id],
+          model: Courier::DeviceSet,
+          options: params[:request_options]
+        )
+      end
+
+      # Create a named, reusable set of preview devices. Every id must be one listed by
+      # `GET /previews/devices`; any other is a 422.
+      #
+      # @overload create_device_set(device_ids:, name:, request_options: {})
+      #
+      # @param device_ids [Array<String>] The devices the set contains, by `PreviewDevice.id`. At least one is required.
+      #
+      # @param name [String] Human-readable name.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::DeviceSet]
+      #
+      # @see Courier::Models::PreviewCreateDeviceSetParams
+      def create_device_set(params)
+        parsed, options = Courier::PreviewCreateDeviceSetParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "previews/device-sets",
+          body: parsed,
+          model: Courier::DeviceSet,
+          options: options
+        )
+      end
+
+      # List the workspace's preview sets. Archived sets are not returned.
+      #
+      # @overload list_device_sets(request_options: {})
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::DeviceSetListResponse]
+      #
+      # @see Courier::Models::PreviewListDeviceSetsParams
+      def list_device_sets(params = {})
+        @client.request(
+          method: :get,
+          path: "previews/device-sets",
+          model: Courier::DeviceSetListResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # List the devices a preview can be rendered on. Reference data, identical for
+      # every workspace — these ids are what a device set is built from and what a run
+      # reports results for.
+      #
+      # @overload list_devices(request_options: {})
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::PreviewDeviceListResponse]
+      #
+      # @see Courier::Models::PreviewListDevicesParams
+      def list_devices(params = {})
+        @client.request(
+          method: :get,
+          path: "previews/devices",
+          model: Courier::PreviewDeviceListResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::PreviewRetrieveDeviceSetParams} for more details.
+      #
+      # Retrieve a preview set by ID. Archived sets return 404.
+      #
+      # @overload retrieve_device_set(device_set_id, request_options: {})
+      #
+      # @param device_set_id [String] The preview set to retrieve, identified by the `id` returned when it was created
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::DeviceSet]
+      #
+      # @see Courier::Models::PreviewRetrieveDeviceSetParams
+      def retrieve_device_set(device_set_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["previews/device-sets/%1$s", device_set_id],
+          model: Courier::DeviceSet,
+          options: params[:request_options]
+        )
+      end
+
+      # Replace a device set. This is a full replace, not a patch — both the name and
+      # the device list are always written. The Courier-provided default set cannot be
+      # changed and returns 409.
+      #
+      # @overload update_device_set(device_set_id, device_ids:, name:, request_options: {})
+      #
+      # @param device_set_id [String] The preview set to replace.
+      #
+      # @param device_ids [Array<String>] The devices the set contains, by `PreviewDevice.id`. At least one is required.
+      #
+      # @param name [String] Human-readable name.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::DeviceSet]
+      #
+      # @see Courier::Models::PreviewUpdateDeviceSetParams
+      def update_device_set(device_set_id, params)
+        parsed, options = Courier::PreviewUpdateDeviceSetParams.dump_request(params)
+        @client.request(
+          method: :put,
+          path: ["previews/device-sets/%1$s", device_set_id],
+          body: parsed,
+          model: Courier::DeviceSet,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Courier::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/courier/version.rb

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

data/lib/courier.rb

@@ -83,7 +83,9 @@ require_relative "courier/models/notification_template_create_request"
 require_relative "courier/models/notification_template_publish_request"
 require_relative "courier/models/notification_element_put_request"
 require_relative "courier/models/notification_template_update_request"
+require_relative "courier/models/notifications/previews/create_preview_run_request"
 require_relative "courier/models/notification_template_payload"
+require_relative "courier/models/create_device_set_request"
 require_relative "courier/models/routing_strategy_create_request"
 require_relative "courier/models/routing_strategy_replace_request"
 require_relative "courier/models/base_template_tenant_association"
@@ -174,6 +176,8 @@ require_relative "courier/models/channel_metadata"
 require_relative "courier/models/channel_preference"
 require_relative "courier/models/check"
 require_relative "courier/models/default_preferences"
+require_relative "courier/models/device_set"
+require_relative "courier/models/device_set_list_response"
 require_relative "courier/models/device_type"
 require_relative "courier/models/digest_category"
 require_relative "courier/models/digest_day_of_week"
@@ -334,6 +338,17 @@ require_relative "courier/models/notifications/check_list_params"
 require_relative "courier/models/notifications/check_list_response"
 require_relative "courier/models/notifications/check_update_params"
 require_relative "courier/models/notifications/check_update_response"
+require_relative "courier/models/notifications/previews/preview_result"
+require_relative "courier/models/notifications/previews/preview_result_failure_reason"
+require_relative "courier/models/notifications/previews/preview_result_status"
+require_relative "courier/models/notifications/previews/preview_run"
+require_relative "courier/models/notifications/previews/preview_run_detail"
+require_relative "courier/models/notifications/previews/preview_run_failure_reason"
+require_relative "courier/models/notifications/previews/preview_run_list_response"
+require_relative "courier/models/notifications/previews/preview_run_status"
+require_relative "courier/models/notifications/previews/run_create_params"
+require_relative "courier/models/notifications/previews/run_list_params"
+require_relative "courier/models/notifications/previews/run_retrieve_params"
 require_relative "courier/models/notification_template_alias"
 require_relative "courier/models/notification_template_response"
 require_relative "courier/models/notification_template_state"
@@ -349,6 +364,14 @@ require_relative "courier/models/preference_change_log_entry"
 require_relative "courier/models/preference_change_log_value"
 require_relative "courier/models/preference_logs_list_response"
 require_relative "courier/models/preference_status"
+require_relative "courier/models/preview_archive_device_set_params"
+require_relative "courier/models/preview_create_device_set_params"
+require_relative "courier/models/preview_device"
+require_relative "courier/models/preview_device_list_response"
+require_relative "courier/models/preview_list_device_sets_params"
+require_relative "courier/models/preview_list_devices_params"
+require_relative "courier/models/preview_retrieve_device_set_params"
+require_relative "courier/models/preview_update_device_set_params"
 require_relative "courier/models/profile_create_params"
 require_relative "courier/models/profile_create_response"
 require_relative "courier/models/profile_delete_params"
@@ -513,6 +536,9 @@ require_relative "courier/resources/lists/subscriptions"
 require_relative "courier/resources/messages"
 require_relative "courier/resources/notifications"
 require_relative "courier/resources/notifications/checks"
+require_relative "courier/resources/notifications/previews"
+require_relative "courier/resources/notifications/previews/runs"
+require_relative "courier/resources/previews"
 require_relative "courier/resources/profiles"
 require_relative "courier/resources/profiles/lists"
 require_relative "courier/resources/providers"

data/rbi/courier/client.rbi

@@ -53,6 +53,11 @@ module Courier
     sig { returns(Courier::Resources::Broadcasts) }
     attr_reader :broadcasts
 
+    # Render a template's email content on real email clients and read back the
+    # screenshots, so you can check how it looks before you send it.
+    sig { returns(Courier::Resources::Previews) }
+    attr_reader :previews
+
     sig { returns(Courier::Resources::Bulk) }
     attr_reader :bulk
 

data/rbi/courier/models/create_device_set_request.rbi

@@ -0,0 +1,39 @@
+# typed: strong
+
+module Courier
+  module Models
+    class CreateDeviceSetRequest < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::CreateDeviceSetRequest, Courier::Internal::AnyHash)
+        end
+
+      # The devices the set contains, by `PreviewDevice.id`. At least one is required.
+      sig { returns(T::Array[String]) }
+      attr_accessor :device_ids
+
+      # Human-readable name.
+      sig { returns(String) }
+      attr_accessor :name
+
+      # Request body for creating or replacing a device set. A full replace, not a patch
+      # — both fields are always written.
+      sig do
+        params(device_ids: T::Array[String], name: String).returns(
+          T.attached_class
+        )
+      end
+      def self.new(
+        # The devices the set contains, by `PreviewDevice.id`. At least one is required.
+        device_ids:,
+        # Human-readable name.
+        name:
+      )
+      end
+
+      sig { override.returns({ device_ids: T::Array[String], name: String }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/device_set.rbi

@@ -0,0 +1,81 @@
+# typed: strong
+
+module Courier
+  module Models
+    class DeviceSet < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Courier::DeviceSet, Courier::Internal::AnyHash) }
+
+      # Unique identifier for the device set.
+      sig { returns(String) }
+      attr_accessor :id
+
+      # ISO-8601 timestamp of when the set was created.
+      sig { returns(String) }
+      attr_accessor :created_at
+
+      # The devices in this set, by `PreviewDevice.id`.
+      sig { returns(T::Array[String]) }
+      attr_accessor :device_ids
+
+      # Human-readable name.
+      sig { returns(String) }
+      attr_accessor :name
+
+      # ISO-8601 timestamp of when the set was last written.
+      sig { returns(String) }
+      attr_accessor :updated_at
+
+      # ISO-8601 timestamp of when the set was archived. Present only on the archive
+      # response, which is the one place the state is observable.
+      sig { returns(T.nilable(String)) }
+      attr_reader :archived_at
+
+      sig { params(archived_at: String).void }
+      attr_writer :archived_at
+
+      # A named, reusable list of preview devices.
+      sig do
+        params(
+          id: String,
+          created_at: String,
+          device_ids: T::Array[String],
+          name: String,
+          updated_at: String,
+          archived_at: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Unique identifier for the device set.
+        id:,
+        # ISO-8601 timestamp of when the set was created.
+        created_at:,
+        # The devices in this set, by `PreviewDevice.id`.
+        device_ids:,
+        # Human-readable name.
+        name:,
+        # ISO-8601 timestamp of when the set was last written.
+        updated_at:,
+        # ISO-8601 timestamp of when the set was archived. Present only on the archive
+        # response, which is the one place the state is observable.
+        archived_at: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            created_at: String,
+            device_ids: T::Array[String],
+            name: String,
+            updated_at: String,
+            archived_at: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/device_set_list_response.rbi

@@ -0,0 +1,28 @@
+# typed: strong
+
+module Courier
+  module Models
+    class DeviceSetListResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::DeviceSetListResponse, Courier::Internal::AnyHash)
+        end
+
+      sig { returns(T::Array[Courier::DeviceSet]) }
+      attr_accessor :results
+
+      # The workspace's active device sets. Not paginated.
+      sig do
+        params(results: T::Array[Courier::DeviceSet::OrHash]).returns(
+          T.attached_class
+        )
+      end
+      def self.new(results:)
+      end
+
+      sig { override.returns({ results: T::Array[Courier::DeviceSet] }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/notifications/previews/create_preview_run_request.rbi

@@ -0,0 +1,110 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Notifications
+      module Previews
+        class CreatePreviewRunRequest < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::Notifications::Previews::CreatePreviewRunRequest,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # Template variables to render with, the same shape as the `data` object on a
+          # send.
+          sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+          attr_reader :data
+
+          sig { params(data: T::Hash[Symbol, T.anything]).void }
+          attr_writer :data
+
+          # The devices to render on, by `PreviewDevice.id`, for a one-off run. Mutually
+          # exclusive with `device_set_id`.
+          sig { returns(T.nilable(T::Array[String])) }
+          attr_reader :device_ids
+
+          sig { params(device_ids: T::Array[String]).void }
+          attr_writer :device_ids
+
+          # A saved device set naming the devices to render on. Mutually exclusive with
+          # `device_ids`.
+          sig { returns(T.nilable(String)) }
+          attr_reader :device_set_id
+
+          sig { params(device_set_id: String).void }
+          attr_writer :device_set_id
+
+          # Render the template's content for this locale, e.g. "fr-FR".
+          sig { returns(T.nilable(String)) }
+          attr_reader :locale
+
+          sig { params(locale: String).void }
+          attr_writer :locale
+
+          # Which version of the template to render. Omit for the latest saved draft, which
+          # always exists and is what the editor shows. `published` renders the live
+          # version; a zero-padded `v002` renders that specific publish. Versions are
+          # 1-based, so `v000` is not a version, and the unpadded `v2` is rejected — that
+          # spelling belongs to journeys' AutomationVersionId, a different scheme in which
+          # `v0` means published.
+          sig { returns(T.nilable(String)) }
+          attr_reader :template_version
+
+          sig { params(template_version: String).void }
+          attr_writer :template_version
+
+          # Request body for creating a preview run of the template in the path. Provide
+          # exactly one of `device_set_id` or `device_ids`. The template is the path's
+          # `{id}`; a `template_id` here is an unknown key and a 400.
+          sig do
+            params(
+              data: T::Hash[Symbol, T.anything],
+              device_ids: T::Array[String],
+              device_set_id: String,
+              locale: String,
+              template_version: String
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Template variables to render with, the same shape as the `data` object on a
+            # send.
+            data: nil,
+            # The devices to render on, by `PreviewDevice.id`, for a one-off run. Mutually
+            # exclusive with `device_set_id`.
+            device_ids: nil,
+            # A saved device set naming the devices to render on. Mutually exclusive with
+            # `device_ids`.
+            device_set_id: nil,
+            # Render the template's content for this locale, e.g. "fr-FR".
+            locale: nil,
+            # Which version of the template to render. Omit for the latest saved draft, which
+            # always exists and is what the editor shows. `published` renders the live
+            # version; a zero-padded `v002` renders that specific publish. Versions are
+            # 1-based, so `v000` is not a version, and the unpadded `v2` is rejected — that
+            # spelling belongs to journeys' AutomationVersionId, a different scheme in which
+            # `v0` means published.
+            template_version: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                data: T::Hash[Symbol, T.anything],
+                device_ids: T::Array[String],
+                device_set_id: String,
+                locale: String,
+                template_version: String
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/notifications/previews/preview_result.rbi

@@ -0,0 +1,117 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Notifications
+      PreviewResult = Previews::PreviewResult
+
+      module Previews
+        class PreviewResult < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::Notifications::Previews::PreviewResult,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # The device this result is for, by `PreviewDevice.id`.
+          sig { returns(String) }
+          attr_accessor :device_id
+
+          # Short-lived signed URL for the full-sized image. Null until the screenshot
+          # exists. Re-signed on every read, so fetch it rather than storing it.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :screenshot_url
+
+          # One device's outcome. `COMPLETED` means the screenshot exists and its URLs are
+          # populated. `UNSUPPORTED`, `TIMED_OUT` and `FAILED` are all terminal, and none
+          # stands in for another — `UNSUPPORTED` means the device was retired at the
+          # vendor, `TIMED_OUT` means it did not report in time.
+          sig do
+            returns(
+              Courier::Notifications::Previews::PreviewResultStatus::TaggedSymbol
+            )
+          end
+          attr_accessor :status
+
+          # Short-lived signed URL for the grid-sized image. Null until the screenshot
+          # exists. Re-signed on every read, so fetch it rather than storing it.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :thumbnail_url
+
+          # Why one device's render failed, when its `status` is `FAILED` and the cause has
+          # a public name. `DELIVERY_FAILED` means the rendering service could not deliver
+          # the message to its own capture mailbox — infrastructure, not anything wrong with
+          # the template.
+          sig do
+            returns(
+              T.nilable(
+                Courier::Notifications::Previews::PreviewResultFailureReason::TaggedSymbol
+              )
+            )
+          end
+          attr_reader :failure_reason
+
+          sig do
+            params(
+              failure_reason:
+                Courier::Notifications::Previews::PreviewResultFailureReason::OrSymbol
+            ).void
+          end
+          attr_writer :failure_reason
+
+          # One device's result within a preview run.
+          sig do
+            params(
+              device_id: String,
+              screenshot_url: T.nilable(String),
+              status:
+                Courier::Notifications::Previews::PreviewResultStatus::OrSymbol,
+              thumbnail_url: T.nilable(String),
+              failure_reason:
+                Courier::Notifications::Previews::PreviewResultFailureReason::OrSymbol
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # The device this result is for, by `PreviewDevice.id`.
+            device_id:,
+            # Short-lived signed URL for the full-sized image. Null until the screenshot
+            # exists. Re-signed on every read, so fetch it rather than storing it.
+            screenshot_url:,
+            # One device's outcome. `COMPLETED` means the screenshot exists and its URLs are
+            # populated. `UNSUPPORTED`, `TIMED_OUT` and `FAILED` are all terminal, and none
+            # stands in for another — `UNSUPPORTED` means the device was retired at the
+            # vendor, `TIMED_OUT` means it did not report in time.
+            status:,
+            # Short-lived signed URL for the grid-sized image. Null until the screenshot
+            # exists. Re-signed on every read, so fetch it rather than storing it.
+            thumbnail_url:,
+            # Why one device's render failed, when its `status` is `FAILED` and the cause has
+            # a public name. `DELIVERY_FAILED` means the rendering service could not deliver
+            # the message to its own capture mailbox — infrastructure, not anything wrong with
+            # the template.
+            failure_reason: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                device_id: String,
+                screenshot_url: T.nilable(String),
+                status:
+                  Courier::Notifications::Previews::PreviewResultStatus::TaggedSymbol,
+                thumbnail_url: T.nilable(String),
+                failure_reason:
+                  Courier::Notifications::Previews::PreviewResultFailureReason::TaggedSymbol
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/notifications/previews/preview_result_failure_reason.rbi

@@ -0,0 +1,44 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Notifications
+      PreviewResultFailureReason = Previews::PreviewResultFailureReason
+
+      module Previews
+        # Why one device's render failed, when its `status` is `FAILED` and the cause has
+        # a public name. `DELIVERY_FAILED` means the rendering service could not deliver
+        # the message to its own capture mailbox — infrastructure, not anything wrong with
+        # the template.
+        module PreviewResultFailureReason
+          extend Courier::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Courier::Notifications::Previews::PreviewResultFailureReason
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          DELIVERY_FAILED =
+            T.let(
+              :DELIVERY_FAILED,
+              Courier::Notifications::Previews::PreviewResultFailureReason::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Courier::Notifications::Previews::PreviewResultFailureReason::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end