trycourier 6.9.0 → 6.11.0

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

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/resources/workspace_preferences.rb

@@ -108,6 +108,43 @@ module Courier
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::WorkspacePreferenceListLogsParams} for more details.
+      #
+      # Returns the history of preference changes in this environment, newest first.
+      # Each entry records one change a user made to one subscription topic, and carries
+      # the value before it where there was one. Supply user_id to read a single user's
+      # history instead of the whole environment.
+      #
+      # @overload list_logs(cursor: nil, limit: nil, since: nil, tenant_id: nil, user_id: nil, request_options: {})
+      #
+      # @param cursor [String] A cursor from a previous response's paging.cursor. Continue only while paging.mo
+      #
+      # @param limit [Integer] How many entries to return. Defaults to 25.
+      #
+      # @param since [String] Return only changes at or after this time, as an ISO-8601 date or date-time. A d
+      #
+      # @param tenant_id [String] Narrow to the changes this user made in one tenant context. Only valid together
+      #
+      # @param user_id [String] Return only this user's changes. Omit it to read every change in the environment
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::PreferenceLogsListResponse]
+      #
+      # @see Courier::Models::WorkspacePreferenceListLogsParams
+      def list_logs(params = {})
+        parsed, options = Courier::WorkspacePreferenceListLogsParams.dump_request(params)
+        query = Courier::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "preferences/logs",
+          query: query,
+          model: Courier::PreferenceLogsListResponse,
+          options: options
+        )
+      end
+
       # Some parameter documentations has been truncated, see
       # {Courier::Models::WorkspacePreferencePublishParams} for more details.
       #

data/lib/courier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Courier
-  VERSION = "6.9.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"
@@ -345,7 +360,18 @@ require_relative "courier/models/pagerduty_recipient"
 require_relative "courier/models/paging"
 require_relative "courier/models/post_tenant_template_publish_response"
 require_relative "courier/models/preference"
+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"
@@ -474,6 +500,7 @@ require_relative "courier/models/widget_background"
 require_relative "courier/models/workspace_preference_archive_params"
 require_relative "courier/models/workspace_preference_create_params"
 require_relative "courier/models/workspace_preference_get_response"
+require_relative "courier/models/workspace_preference_list_logs_params"
 require_relative "courier/models/workspace_preference_list_params"
 require_relative "courier/models/workspace_preference_list_response"
 require_relative "courier/models/workspace_preference_publish_params"
@@ -509,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