trycourier 6.10.0 → 6.11.0

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

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

data/rbi/courier/models/preview_archive_device_set_params.rbi

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

data/rbi/courier/models/preview_create_device_set_params.rbi

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

data/rbi/courier/models/preview_device.rbi

@@ -0,0 +1,168 @@
+# typed: strong
+
+module Courier
+  module Models
+    class PreviewDevice < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::PreviewDevice, Courier::Internal::AnyHash)
+        end
+
+      # The device's identifier, used in `device_ids` when creating a device set or a
+      # run.
+      sig { returns(String) }
+      attr_accessor :id
+
+      # The mail app. For webmail it is the service (`outlook_com`, `gmail_com`); for
+      # mobile the app (`apple_mail`, `gmail`); for desktop the app together with the
+      # version it is sold under (`outlook_2019`, `outlook_microsoft_365`,
+      # `apple_mail_16`), because that version is what separates one desktop Outlook
+      # from another.
+      sig { returns(String) }
+      attr_accessor :app
+
+      # Where the app runs.
+      sig { returns(Courier::PreviewDevice::Category::TaggedSymbol) }
+      attr_accessor :category
+
+      # Display name. Render it as-is rather than parsing it. It is also what separates
+      # the two 120-dpi Outlook renders from their 100% siblings, which are otherwise
+      # identical field for field.
+      sig { returns(String) }
+      attr_accessor :name
+
+      # The operating system.
+      sig { returns(String) }
+      attr_accessor :os
+
+      # The operating system's version. Always set.
+      sig { returns(String) }
+      attr_accessor :os_version
+
+      # What the app runs on — the browser for webmail (`chrome`, `edge`, `firefox`),
+      # the phone for mobile (`iphone`, `pixel`). Null for desktop, where the app runs
+      # on nothing but the OS.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :platform
+
+      # Which one of the platform — the phone model for mobile (`15_pro_max`, `10`).
+      # Null for webmail, which always renders in the current browser, and for desktop.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :platform_version
+
+      # Whether the email is rendered in light or dark mode.
+      sig { returns(Courier::PreviewDevice::Theme::TaggedSymbol) }
+      attr_accessor :theme
+
+      # One mail app on one platform, operating system and theme that a preview can be
+      # rendered on. Reference data, identical for every workspace. Every field is
+      # always present; `platform` and `platform_version` are null where they do not
+      # apply.
+      sig do
+        params(
+          id: String,
+          app: String,
+          category: Courier::PreviewDevice::Category::OrSymbol,
+          name: String,
+          os: String,
+          os_version: String,
+          platform: T.nilable(String),
+          platform_version: T.nilable(String),
+          theme: Courier::PreviewDevice::Theme::OrSymbol
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The device's identifier, used in `device_ids` when creating a device set or a
+        # run.
+        id:,
+        # The mail app. For webmail it is the service (`outlook_com`, `gmail_com`); for
+        # mobile the app (`apple_mail`, `gmail`); for desktop the app together with the
+        # version it is sold under (`outlook_2019`, `outlook_microsoft_365`,
+        # `apple_mail_16`), because that version is what separates one desktop Outlook
+        # from another.
+        app:,
+        # Where the app runs.
+        category:,
+        # Display name. Render it as-is rather than parsing it. It is also what separates
+        # the two 120-dpi Outlook renders from their 100% siblings, which are otherwise
+        # identical field for field.
+        name:,
+        # The operating system.
+        os:,
+        # The operating system's version. Always set.
+        os_version:,
+        # What the app runs on — the browser for webmail (`chrome`, `edge`, `firefox`),
+        # the phone for mobile (`iphone`, `pixel`). Null for desktop, where the app runs
+        # on nothing but the OS.
+        platform:,
+        # Which one of the platform — the phone model for mobile (`15_pro_max`, `10`).
+        # Null for webmail, which always renders in the current browser, and for desktop.
+        platform_version:,
+        # Whether the email is rendered in light or dark mode.
+        theme:
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            app: String,
+            category: Courier::PreviewDevice::Category::TaggedSymbol,
+            name: String,
+            os: String,
+            os_version: String,
+            platform: T.nilable(String),
+            platform_version: T.nilable(String),
+            theme: Courier::PreviewDevice::Theme::TaggedSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Where the app runs.
+      module Category
+        extend Courier::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Courier::PreviewDevice::Category) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        WEBMAIL =
+          T.let(:webmail, Courier::PreviewDevice::Category::TaggedSymbol)
+        MOBILE = T.let(:mobile, Courier::PreviewDevice::Category::TaggedSymbol)
+        DESKTOP =
+          T.let(:desktop, Courier::PreviewDevice::Category::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Courier::PreviewDevice::Category::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+
+      # Whether the email is rendered in light or dark mode.
+      module Theme
+        extend Courier::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Courier::PreviewDevice::Theme) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        LIGHT = T.let(:light, Courier::PreviewDevice::Theme::TaggedSymbol)
+        DARK = T.let(:dark, Courier::PreviewDevice::Theme::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Courier::PreviewDevice::Theme::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/preview_device_list_response.rbi

@@ -0,0 +1,28 @@
+# typed: strong
+
+module Courier
+  module Models
+    class PreviewDeviceListResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::PreviewDeviceListResponse, Courier::Internal::AnyHash)
+        end
+
+      sig { returns(T::Array[Courier::PreviewDevice]) }
+      attr_accessor :results
+
+      # The full catalog of renderable devices. Not paginated.
+      sig do
+        params(results: T::Array[Courier::PreviewDevice::OrHash]).returns(
+          T.attached_class
+        )
+      end
+      def self.new(results:)
+      end
+
+      sig { override.returns({ results: T::Array[Courier::PreviewDevice] }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/preview_list_device_sets_params.rbi

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

data/rbi/courier/models/preview_list_devices_params.rbi

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

data/rbi/courier/models/preview_retrieve_device_set_params.rbi

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

data/rbi/courier/models/preview_update_device_set_params.rbi

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

data/rbi/courier/models.rbi

@@ -144,10 +144,16 @@ module Courier
 
   CreateBroadcastRequest = Courier::Models::CreateBroadcastRequest
 
+  CreateDeviceSetRequest = Courier::Models::CreateDeviceSetRequest
+
   CreateJourneyRequest = Courier::Models::CreateJourneyRequest
 
   DefaultPreferences = Courier::Models::DefaultPreferences
 
+  DeviceSet = Courier::Models::DeviceSet
+
+  DeviceSetListResponse = Courier::Models::DeviceSetListResponse
+
   DeviceType = Courier::Models::DeviceType
 
   DigestCategory = Courier::Models::DigestCategory
@@ -503,6 +509,23 @@ module Courier
 
   PreferenceStatus = Courier::Models::PreferenceStatus
 
+  PreviewArchiveDeviceSetParams = Courier::Models::PreviewArchiveDeviceSetParams
+
+  PreviewCreateDeviceSetParams = Courier::Models::PreviewCreateDeviceSetParams
+
+  PreviewDevice = Courier::Models::PreviewDevice
+
+  PreviewDeviceListResponse = Courier::Models::PreviewDeviceListResponse
+
+  PreviewListDeviceSetsParams = Courier::Models::PreviewListDeviceSetsParams
+
+  PreviewListDevicesParams = Courier::Models::PreviewListDevicesParams
+
+  PreviewRetrieveDeviceSetParams =
+    Courier::Models::PreviewRetrieveDeviceSetParams
+
+  PreviewUpdateDeviceSetParams = Courier::Models::PreviewUpdateDeviceSetParams
+
   ProfileCreateParams = Courier::Models::ProfileCreateParams
 
   ProfileDeleteParams = Courier::Models::ProfileDeleteParams

data/rbi/courier/resources/notifications/previews/runs.rbi

@@ -0,0 +1,136 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Notifications
+      class Previews
+        # 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 Runs
+          # Render this template's email content on each of the requested devices.
+          #
+          # Returns as soon as the run exists and its render is queued — the screenshots are
+          # produced asynchronously. Poll
+          # `GET /notifications/{id}/previews/runs/{previewRunId}` until every result
+          # reaches a terminal status.
+          #
+          # Name the devices either with `device_set_id`, for a saved set, or with
+          # `device_ids`, for a one-off list. Exactly one of the two is required. Inline
+          # `device_ids` must be ids listed by `GET /previews/devices`; any other id is a
+          # 422, refused before the run exists or is billed.
+          #
+          # A template that does not exist is a 404. One that exists but cannot be previewed
+          # — not a Design Studio template, no email channel, or no such `template_version`
+          # — is a 422, also refused before the run exists or is billed.
+          #
+          # Preview runs are a metered add-on. A workspace without it, or with its billing
+          # suspended, receives a 402.
+          sig do
+            params(
+              id: String,
+              data: T::Hash[Symbol, T.anything],
+              device_ids: T::Array[String],
+              device_set_id: String,
+              locale: String,
+              template_version: String,
+              idempotency_key: String,
+              x_idempotency_expiration: String,
+              request_options: Courier::RequestOptions::OrHash
+            ).returns(Courier::Notifications::Previews::PreviewRun)
+          end
+          def create(
+            # Path param: Template ID (nt\_ prefix). Must be a Design Studio template.
+            id,
+            # Body param: Template variables to render with, the same shape as the `data`
+            # object on a send.
+            data: nil,
+            # Body param: The devices to render on, by `PreviewDevice.id`, for a one-off run.
+            # Mutually exclusive with `device_set_id`.
+            device_ids: nil,
+            # Body param: A saved device set naming the devices to render on. Mutually
+            # exclusive with `device_ids`.
+            device_set_id: nil,
+            # Body param: Render the template's content for this locale, e.g. "fr-FR".
+            locale: nil,
+            # Body param: 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,
+            # Header param: A unique key that makes this request idempotent. If Courier
+            # receives another request with the same `Idempotency-Key`, it returns the stored
+            # response from the first request without performing the operation again
+            # (including the original status code and any error). Use it to safely retry
+            # `POST` requests after network failures without risking duplicate sends. The key
+            # is scoped to this endpoint.
+            idempotency_key: nil,
+            # Header param: How long the idempotency key remains valid, as a Unix epoch
+            # timestamp in seconds or an ISO 8601 date string. Only applies when
+            # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+            # maximum is 1 year.
+            x_idempotency_expiration: nil,
+            request_options: {}
+          )
+          end
+
+          # Retrieve one of this template's preview runs together with its per-device
+          # results.
+          #
+          # A run is only readable under the template it previewed: under any other template
+          # it is a 404, the same as a run that does not exist.
+          #
+          # `thumbnail_url` and `screenshot_url` are short-lived signed URLs, re-signed on
+          # every read. Fetch them now rather than storing them. Both are null until
+          # Courier's own copy of the image exists, which is what `status: COMPLETED` on a
+          # result means.
+          sig do
+            params(
+              preview_run_id: String,
+              id: String,
+              request_options: Courier::RequestOptions::OrHash
+            ).returns(Courier::Notifications::Previews::PreviewRunDetail)
+          end
+          def retrieve(
+            # The preview run to retrieve, identified by the `id` returned when it was
+            # created.
+            preview_run_id,
+            # Template ID (nt\_ prefix).
+            id:,
+            request_options: {}
+          )
+          end
+
+          # List this template's preview runs, newest first. Cursor-paginated.
+          #
+          # A template that does not exist is a 404, the same as every other
+          # `/notifications/{id}` route.
+          sig do
+            params(
+              id: String,
+              cursor: T.nilable(String),
+              limit: Integer,
+              request_options: Courier::RequestOptions::OrHash
+            ).returns(Courier::Notifications::Previews::PreviewRunListResponse)
+          end
+          def list(
+            # Template ID (nt\_ prefix).
+            id,
+            # Opaque pagination cursor from a previous response. Omit for the first page.
+            cursor: nil,
+            # Maximum number of results per page.
+            limit: nil,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Courier::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/resources/notifications/previews.rbi

@@ -0,0 +1,19 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Notifications
+      class Previews
+        # 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::Notifications::Previews::Runs) }
+        attr_reader :runs
+
+        # @api private
+        sig { params(client: Courier::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/courier/resources/notifications.rbi

@@ -10,6 +10,9 @@ module Courier
       sig { returns(Courier::Resources::Notifications::Checks) }
       attr_reader :checks
 
+      sig { returns(Courier::Resources::Notifications::Previews) }
+      attr_reader :previews
+
       # Create a notification template. Requires all fields in the notification object.
       # Templates are created in draft state by default.
       #