trycourier 6.10.0 → 6.11.0

data/lib/courier/models/notifications/previews/run_list_params.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    module Notifications
+      module Previews
+        # @see Courier::Resources::Notifications::Previews::Runs#list
+        class RunListParams < Courier::Internal::Type::BaseModel
+          extend Courier::Internal::Type::RequestParameters::Converter
+          include Courier::Internal::Type::RequestParameters
+
+          # @!attribute id
+          #
+          #   @return [String]
+          required :id, String
+
+          # @!attribute cursor
+          #   Opaque pagination cursor from a previous response. Omit for the first page.
+          #
+          #   @return [String, nil]
+          optional :cursor, String, nil?: true
+
+          # @!attribute limit
+          #   Maximum number of results per page.
+          #
+          #   @return [Integer, nil]
+          optional :limit, Integer
+
+          # @!method initialize(id:, cursor: nil, limit: nil, request_options: {})
+          #   @param id [String]
+          #
+          #   @param cursor [String, nil] Opaque pagination cursor from a previous response. Omit for the first page.
+          #
+          #   @param limit [Integer] Maximum number of results per page.
+          #
+          #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+        end
+      end
+    end
+  end
+end

data/lib/courier/models/notifications/previews/run_retrieve_params.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    module Notifications
+      module Previews
+        # @see Courier::Resources::Notifications::Previews::Runs#retrieve
+        class RunRetrieveParams < Courier::Internal::Type::BaseModel
+          extend Courier::Internal::Type::RequestParameters::Converter
+          include Courier::Internal::Type::RequestParameters
+
+          # @!attribute id
+          #
+          #   @return [String]
+          required :id, String
+
+          # @!attribute preview_run_id
+          #
+          #   @return [String]
+          required :preview_run_id, String
+
+          # @!method initialize(id:, preview_run_id:, request_options: {})
+          #   @param id [String]
+          #   @param preview_run_id [String]
+          #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+        end
+      end
+    end
+  end
+end

data/lib/courier/models/preview_archive_device_set_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#archive_device_set
+    class PreviewArchiveDeviceSetParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!attribute device_set_id
+      #
+      #   @return [String]
+      required :device_set_id, String
+
+      # @!method initialize(device_set_id:, request_options: {})
+      #   @param device_set_id [String]
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models/preview_create_device_set_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#create_device_set
+    class PreviewCreateDeviceSetParams < Courier::Models::CreateDeviceSetRequest
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models/preview_device.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    class PreviewDevice < Courier::Internal::Type::BaseModel
+      # @!attribute id
+      #   The device's identifier, used in `device_ids` when creating a device set or a
+      #   run.
+      #
+      #   @return [String]
+      required :id, String
+
+      # @!attribute app
+      #   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.
+      #
+      #   @return [String]
+      required :app, String
+
+      # @!attribute category
+      #   Where the app runs.
+      #
+      #   @return [Symbol, Courier::Models::PreviewDevice::Category]
+      required :category, enum: -> { Courier::PreviewDevice::Category }
+
+      # @!attribute name
+      #   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.
+      #
+      #   @return [String]
+      required :name, String
+
+      # @!attribute os
+      #   The operating system.
+      #
+      #   @return [String]
+      required :os, String
+
+      # @!attribute os_version
+      #   The operating system's version. Always set.
+      #
+      #   @return [String]
+      required :os_version, String
+
+      # @!attribute platform
+      #   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.
+      #
+      #   @return [String, nil]
+      required :platform, String, nil?: true
+
+      # @!attribute platform_version
+      #   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.
+      #
+      #   @return [String, nil]
+      required :platform_version, String, nil?: true
+
+      # @!attribute theme
+      #   Whether the email is rendered in light or dark mode.
+      #
+      #   @return [Symbol, Courier::Models::PreviewDevice::Theme]
+      required :theme, enum: -> { Courier::PreviewDevice::Theme }
+
+      # @!method initialize(id:, app:, category:, name:, os:, os_version:, platform:, platform_version:, theme:)
+      #   Some parameter documentations has been truncated, see
+      #   {Courier::Models::PreviewDevice} for more details.
+      #
+      #   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.
+      #
+      #   @param id [String] The device's identifier, used in `device_ids` when creating a device set or a ru
+      #
+      #   @param app [String] The mail app. For webmail it is the service (`outlook_com`, `gmail_com`); for mo
+      #
+      #   @param category [Symbol, Courier::Models::PreviewDevice::Category] Where the app runs.
+      #
+      #   @param name [String] Display name. Render it as-is rather than parsing it. It is also what separates
+      #
+      #   @param os [String] The operating system.
+      #
+      #   @param os_version [String] The operating system's version. Always set.
+      #
+      #   @param platform [String, nil] What the app runs on — the browser for webmail (`chrome`, `edge`, `firefox`), th
+      #
+      #   @param platform_version [String, nil] Which one of the platform — the phone model for mobile (`15_pro_max`, `10`). Nul
+      #
+      #   @param theme [Symbol, Courier::Models::PreviewDevice::Theme] Whether the email is rendered in light or dark mode.
+
+      # Where the app runs.
+      #
+      # @see Courier::Models::PreviewDevice#category
+      module Category
+        extend Courier::Internal::Type::Enum
+
+        WEBMAIL = :webmail
+        MOBILE = :mobile
+        DESKTOP = :desktop
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # Whether the email is rendered in light or dark mode.
+      #
+      # @see Courier::Models::PreviewDevice#theme
+      module Theme
+        extend Courier::Internal::Type::Enum
+
+        LIGHT = :light
+        DARK = :dark
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/courier/models/preview_device_list_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#list_devices
+    class PreviewDeviceListResponse < Courier::Internal::Type::BaseModel
+      # @!attribute results
+      #
+      #   @return [Array<Courier::Models::PreviewDevice>]
+      required :results, -> { Courier::Internal::Type::ArrayOf[Courier::PreviewDevice] }
+
+      # @!method initialize(results:)
+      #   The full catalog of renderable devices. Not paginated.
+      #
+      #   @param results [Array<Courier::Models::PreviewDevice>]
+    end
+  end
+end

data/lib/courier/models/preview_list_device_sets_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#list_device_sets
+    class PreviewListDeviceSetsParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models/preview_list_devices_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#list_devices
+    class PreviewListDevicesParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models/preview_retrieve_device_set_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#retrieve_device_set
+    class PreviewRetrieveDeviceSetParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!attribute device_set_id
+      #
+      #   @return [String]
+      required :device_set_id, String
+
+      # @!method initialize(device_set_id:, request_options: {})
+      #   @param device_set_id [String]
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models/preview_update_device_set_params.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # @see Courier::Resources::Previews#update_device_set
+    class PreviewUpdateDeviceSetParams < Courier::Models::CreateDeviceSetRequest
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      # @!attribute device_set_id
+      #
+      #   @return [String]
+      required :device_set_id, String
+
+      # @!method initialize(device_set_id:, request_options: {})
+      #   @param device_set_id [String]
+      #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/courier/models.rb

@@ -179,10 +179,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
@@ -525,6 +531,22 @@ 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/lib/courier/resources/notifications/previews/runs.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+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
+          # Some parameter documentations has been truncated, see
+          # {Courier::Models::Notifications::Previews::RunCreateParams} for more details.
+          #
+          # 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.
+          #
+          # @overload create(id, data: nil, device_ids: nil, device_set_id: nil, locale: nil, template_version: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+          #
+          # @param id [String] Path param: Template ID (nt\_ prefix). Must be a Design Studio template.
+          #
+          # @param data [Hash{Symbol=>Object}] Body param: Template variables to render with, the same shape as the `data` obje
+          #
+          # @param device_ids [Array<String>] Body param: The devices to render on, by `PreviewDevice.id`, for a one-off run.
+          #
+          # @param device_set_id [String] Body param: A saved device set naming the devices to render on. Mutually exclusi
+          #
+          # @param locale [String] Body param: Render the template's content for this locale, e.g. "fr-FR".
+          #
+          # @param template_version [String] Body param: Which version of the template to render. Omit for the latest saved d
+          #
+          # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+          #
+          # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
+          #
+          # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Courier::Models::Notifications::Previews::PreviewRun]
+          #
+          # @see Courier::Models::Notifications::Previews::RunCreateParams
+          def create(id, params = {})
+            parsed, options = Courier::Notifications::Previews::RunCreateParams.dump_request(params)
+            header_params =
+              {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
+            @client.request(
+              method: :post,
+              path: ["notifications/%1$s/previews/runs", id],
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: Courier::Notifications::Previews::PreviewRun,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Courier::Models::Notifications::Previews::RunRetrieveParams} for more details.
+          #
+          # 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.
+          #
+          # @overload retrieve(preview_run_id, id:, request_options: {})
+          #
+          # @param preview_run_id [String] The preview run to retrieve, identified by the `id` returned when it was created
+          #
+          # @param id [String] Template ID (nt\_ prefix).
+          #
+          # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Courier::Models::Notifications::Previews::PreviewRunDetail]
+          #
+          # @see Courier::Models::Notifications::Previews::RunRetrieveParams
+          def retrieve(preview_run_id, params)
+            parsed, options = Courier::Notifications::Previews::RunRetrieveParams.dump_request(params)
+            id =
+              parsed.delete(:id) do
+                raise ArgumentError.new("missing required path argument #{_1}")
+              end
+            @client.request(
+              method: :get,
+              path: ["notifications/%1$s/previews/runs/%2$s", id, preview_run_id],
+              model: Courier::Notifications::Previews::PreviewRunDetail,
+              options: 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.
+          #
+          # @overload list(id, cursor: nil, limit: nil, request_options: {})
+          #
+          # @param id [String] Template ID (nt\_ prefix).
+          #
+          # @param cursor [String, nil] Opaque pagination cursor from a previous response. Omit for the first page.
+          #
+          # @param limit [Integer] Maximum number of results per page.
+          #
+          # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Courier::Models::Notifications::Previews::PreviewRunListResponse]
+          #
+          # @see Courier::Models::Notifications::Previews::RunListParams
+          def list(id, params = {})
+            parsed, options = Courier::Notifications::Previews::RunListParams.dump_request(params)
+            query = Courier::Internal::Util.encode_query_params(parsed)
+            @client.request(
+              method: :get,
+              path: ["notifications/%1$s/previews/runs", id],
+              query: query,
+              model: Courier::Notifications::Previews::PreviewRunListResponse,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Courier::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/courier/resources/notifications/previews.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+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.
+        # @return [Courier::Resources::Notifications::Previews::Runs]
+        attr_reader :runs
+
+        # @api private
+        #
+        # @param client [Courier::Client]
+        def initialize(client:)
+          @client = client
+          @runs = Courier::Resources::Notifications::Previews::Runs.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/courier/resources/notifications.rb

@@ -10,6 +10,9 @@ module Courier
       # @return [Courier::Resources::Notifications::Checks]
       attr_reader :checks
 
+      # @return [Courier::Resources::Notifications::Previews]
+      attr_reader :previews
+
       # Some parameter documentations has been truncated, see
       # {Courier::Models::NotificationCreateParams} for more details.
       #
@@ -422,6 +425,7 @@ module Courier
       def initialize(client:)
         @client = client
         @checks = Courier::Resources::Notifications::Checks.new(client: client)
+        @previews = Courier::Resources::Notifications::Previews.new(client: client)
       end
     end
   end