trycourier 6.5.0 → 6.6.0

data/rbi/courier/models/topic_digest_request.rbi

@@ -0,0 +1,95 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestRequest < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::TopicDigestRequest, Courier::Internal::AnyHash)
+        end
+
+      # The cadences this digest delivers on. At least one is required: a digest with no
+      # schedule collects events into an instance that can never fire. Omitting the key
+      # on a replace leaves stored schedules untouched; sending `[]` is a `400`.
+      sig { returns(T::Array[Courier::TopicDigestScheduleRequest]) }
+      attr_accessor :schedules
+
+      # The notification template that renders the digest. A digest with no template
+      # collects nothing, so this is required.
+      sig { returns(String) }
+      attr_accessor :template_id
+
+      # Optional audience the digest is scoped to.
+      sig { returns(T.nilable(String)) }
+      attr_reader :audience_id
+
+      sig { params(audience_id: String).void }
+      attr_writer :audience_id
+
+      # Retention rules per category key. Defaults to a single `digest` category
+      # retaining `FIRST`.
+      sig { returns(T.nilable(T::Array[Courier::TopicDigestCategory])) }
+      attr_reader :categories
+
+      sig do
+        params(categories: T::Array[Courier::TopicDigestCategory::OrHash]).void
+      end
+      attr_writer :categories
+
+      # Whether to deliver the digest even when nothing was collected.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :trigger_empty
+
+      sig { params(trigger_empty: T::Boolean).void }
+      attr_writer :trigger_empty
+
+      # A topic's digest configuration: the template that renders it, the cadences it
+      # delivers on, and how collected events are retained.
+      #
+      # Send `null` for the whole object to turn a digest off, which unlinks the
+      # template and removes its schedules. There is no `enabled` flag, and
+      # `schedules: []` is rejected, because both states are un-deliverable rather than
+      # merely off.
+      sig do
+        params(
+          schedules: T::Array[Courier::TopicDigestScheduleRequest::OrHash],
+          template_id: String,
+          audience_id: String,
+          categories: T::Array[Courier::TopicDigestCategory::OrHash],
+          trigger_empty: T::Boolean
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The cadences this digest delivers on. At least one is required: a digest with no
+        # schedule collects events into an instance that can never fire. Omitting the key
+        # on a replace leaves stored schedules untouched; sending `[]` is a `400`.
+        schedules:,
+        # The notification template that renders the digest. A digest with no template
+        # collects nothing, so this is required.
+        template_id:,
+        # Optional audience the digest is scoped to.
+        audience_id: nil,
+        # Retention rules per category key. Defaults to a single `digest` category
+        # retaining `FIRST`.
+        categories: nil,
+        # Whether to deliver the digest even when nothing was collected.
+        trigger_empty: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            schedules: T::Array[Courier::TopicDigestScheduleRequest],
+            template_id: String,
+            audience_id: String,
+            categories: T::Array[Courier::TopicDigestCategory],
+            trigger_empty: T::Boolean
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/topic_digest_response.rbi

@@ -0,0 +1,98 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::TopicDigestResponse, Courier::Internal::AnyHash)
+        end
+
+      # Retention rules per category key.
+      sig { returns(T::Array[Courier::TopicDigestCategory]) }
+      attr_accessor :categories
+
+      # The digest's delivery cadences, each with its server-assigned `schedule_id`.
+      sig { returns(T::Array[Courier::TopicDigestScheduleResponse]) }
+      attr_accessor :schedules
+
+      # The notification template that renders the digest.
+      sig { returns(String) }
+      attr_accessor :template_id
+
+      # The audience the digest is scoped to, when set.
+      sig { returns(T.nilable(String)) }
+      attr_reader :audience_id
+
+      sig { params(audience_id: String).void }
+      attr_writer :audience_id
+
+      # ISO-8601 timestamp of when the digest was configured.
+      sig { returns(T.nilable(String)) }
+      attr_reader :created
+
+      sig { params(created: String).void }
+      attr_writer :created
+
+      # Whether the digest is delivered even when nothing was collected.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :trigger_empty
+
+      sig { params(trigger_empty: T::Boolean).void }
+      attr_writer :trigger_empty
+
+      # ISO-8601 timestamp of the last update.
+      sig { returns(T.nilable(String)) }
+      attr_reader :updated
+
+      sig { params(updated: String).void }
+      attr_writer :updated
+
+      # A topic's digest configuration.
+      sig do
+        params(
+          categories: T::Array[Courier::TopicDigestCategory::OrHash],
+          schedules: T::Array[Courier::TopicDigestScheduleResponse::OrHash],
+          template_id: String,
+          audience_id: String,
+          created: String,
+          trigger_empty: T::Boolean,
+          updated: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Retention rules per category key.
+        categories:,
+        # The digest's delivery cadences, each with its server-assigned `schedule_id`.
+        schedules:,
+        # The notification template that renders the digest.
+        template_id:,
+        # The audience the digest is scoped to, when set.
+        audience_id: nil,
+        # ISO-8601 timestamp of when the digest was configured.
+        created: nil,
+        # Whether the digest is delivered even when nothing was collected.
+        trigger_empty: nil,
+        # ISO-8601 timestamp of the last update.
+        updated: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            categories: T::Array[Courier::TopicDigestCategory],
+            schedules: T::Array[Courier::TopicDigestScheduleResponse],
+            template_id: String,
+            audience_id: String,
+            created: String,
+            trigger_empty: T::Boolean,
+            updated: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/topic_digest_schedule_request.rbi

@@ -0,0 +1,141 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestScheduleRequest < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::TopicDigestScheduleRequest, Courier::Internal::AnyHash)
+        end
+
+      # How often a digest is delivered. `instant` delivers immediately without
+      # batching, and is the one value that takes no `time`.
+      sig { returns(Courier::DigestFrequency::OrSymbol) }
+      attr_accessor :frequency
+
+      # Required when `frequency` is `monthly`.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :day_of_month
+
+      sig { params(day_of_month: Integer).void }
+      attr_writer :day_of_month
+
+      # Required when `frequency` is `weekly`.
+      sig { returns(T.nilable(Courier::DigestDayOfWeek::OrSymbol)) }
+      attr_reader :day_of_week
+
+      sig { params(day_of_week: Courier::DigestDayOfWeek::OrSymbol).void }
+      attr_writer :day_of_week
+
+      # Required when `frequency` is `custom_days`.
+      sig { returns(T.nilable(T::Array[Courier::DigestDayOfWeek::OrSymbol])) }
+      attr_reader :days_of_week
+
+      sig do
+        params(days_of_week: T::Array[Courier::DigestDayOfWeek::OrSymbol]).void
+      end
+      attr_writer :days_of_week
+
+      # Whether the schedule is disabled.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :disabled
+
+      sig { params(disabled: T::Boolean).void }
+      attr_writer :disabled
+
+      # The schedule recipients are placed on when they have not chosen one. Set this
+      # explicitly rather than relying on array position.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :is_default
+
+      sig { params(is_default: T::Boolean).void }
+      attr_writer :is_default
+
+      # Identifier of an existing schedule to update. Omit when creating a new one.
+      sig { returns(T.nilable(String)) }
+      attr_reader :schedule_id
+
+      sig { params(schedule_id: String).void }
+      attr_writer :schedule_id
+
+      # 24-hour local delivery time, `HH:MM`. Required for every frequency except
+      # `instant`.
+      sig { returns(T.nilable(String)) }
+      attr_reader :time
+
+      sig { params(time: String).void }
+      attr_writer :time
+
+      # IANA timezone the `time` and day fields are expressed in, e.g.
+      # `America/New_York`. Absent means UTC. Delivery follows the same local wall-clock
+      # across daylight-saving changes.
+      sig { returns(T.nilable(String)) }
+      attr_reader :timezone
+
+      sig { params(timezone: String).void }
+      attr_writer :timezone
+
+      # One delivery cadence for a topic's digest. Supply `schedule_id` to update an
+      # existing schedule in place; omit it and one is assigned and returned. The
+      # `schedules` array is a full replacement, so a stored schedule absent from it is
+      # deleted along with its delivery rule.
+      sig do
+        params(
+          frequency: Courier::DigestFrequency::OrSymbol,
+          day_of_month: Integer,
+          day_of_week: Courier::DigestDayOfWeek::OrSymbol,
+          days_of_week: T::Array[Courier::DigestDayOfWeek::OrSymbol],
+          disabled: T::Boolean,
+          is_default: T::Boolean,
+          schedule_id: String,
+          time: String,
+          timezone: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # How often a digest is delivered. `instant` delivers immediately without
+        # batching, and is the one value that takes no `time`.
+        frequency:,
+        # Required when `frequency` is `monthly`.
+        day_of_month: nil,
+        # Required when `frequency` is `weekly`.
+        day_of_week: nil,
+        # Required when `frequency` is `custom_days`.
+        days_of_week: nil,
+        # Whether the schedule is disabled.
+        disabled: nil,
+        # The schedule recipients are placed on when they have not chosen one. Set this
+        # explicitly rather than relying on array position.
+        is_default: nil,
+        # Identifier of an existing schedule to update. Omit when creating a new one.
+        schedule_id: nil,
+        # 24-hour local delivery time, `HH:MM`. Required for every frequency except
+        # `instant`.
+        time: nil,
+        # IANA timezone the `time` and day fields are expressed in, e.g.
+        # `America/New_York`. Absent means UTC. Delivery follows the same local wall-clock
+        # across daylight-saving changes.
+        timezone: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            frequency: Courier::DigestFrequency::OrSymbol,
+            day_of_month: Integer,
+            day_of_week: Courier::DigestDayOfWeek::OrSymbol,
+            days_of_week: T::Array[Courier::DigestDayOfWeek::OrSymbol],
+            disabled: T::Boolean,
+            is_default: T::Boolean,
+            schedule_id: String,
+            time: String,
+            timezone: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/topic_digest_schedule_response.rbi

@@ -0,0 +1,159 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestScheduleResponse < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Courier::TopicDigestScheduleResponse,
+            Courier::Internal::AnyHash
+          )
+        end
+
+      # The schedule's identifier, assigned by the server. This is the value the
+      # `/digests/schedules/{schedule_id}` endpoints are keyed by.
+      sig { returns(String) }
+      attr_accessor :schedule_id
+
+      # ISO-8601 timestamp of when the schedule was created.
+      sig { returns(T.nilable(String)) }
+      attr_reader :created
+
+      sig { params(created: String).void }
+      attr_writer :created
+
+      # Day of the month, 1-31.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :day_of_month
+
+      sig { params(day_of_month: Integer).void }
+      attr_writer :day_of_month
+
+      # A day of the week. Accepted case-insensitively, returned lowercase.
+      sig { returns(T.nilable(Courier::DigestDayOfWeek::TaggedSymbol)) }
+      attr_reader :day_of_week
+
+      sig { params(day_of_week: Courier::DigestDayOfWeek::OrSymbol).void }
+      attr_writer :day_of_week
+
+      sig do
+        returns(T.nilable(T::Array[Courier::DigestDayOfWeek::TaggedSymbol]))
+      end
+      attr_reader :days_of_week
+
+      sig do
+        params(days_of_week: T::Array[Courier::DigestDayOfWeek::OrSymbol]).void
+      end
+      attr_writer :days_of_week
+
+      # Whether the schedule is disabled.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :disabled
+
+      sig { params(disabled: T::Boolean).void }
+      attr_writer :disabled
+
+      # Omitted for a stored schedule this enum cannot express. Those schedules never
+      # fire, but their `schedule_id` is still returned so the `/digests/*` endpoints
+      # remain reachable for them.
+      sig { returns(T.nilable(Courier::DigestFrequency::TaggedSymbol)) }
+      attr_reader :frequency
+
+      sig { params(frequency: Courier::DigestFrequency::OrSymbol).void }
+      attr_writer :frequency
+
+      # Whether this is the schedule recipients are placed on by default.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :is_default
+
+      sig { params(is_default: T::Boolean).void }
+      attr_writer :is_default
+
+      # 24-hour local delivery time, `HH:MM`.
+      sig { returns(T.nilable(String)) }
+      attr_reader :time
+
+      sig { params(time: String).void }
+      attr_writer :time
+
+      # IANA timezone the schedule is expressed in. Absent means UTC.
+      sig { returns(T.nilable(String)) }
+      attr_reader :timezone
+
+      sig { params(timezone: String).void }
+      attr_writer :timezone
+
+      # ISO-8601 timestamp of the last update.
+      sig { returns(T.nilable(String)) }
+      attr_reader :updated
+
+      sig { params(updated: String).void }
+      attr_writer :updated
+
+      # A delivery cadence for a topic's digest, with its assigned id.
+      sig do
+        params(
+          schedule_id: String,
+          created: String,
+          day_of_month: Integer,
+          day_of_week: Courier::DigestDayOfWeek::OrSymbol,
+          days_of_week: T::Array[Courier::DigestDayOfWeek::OrSymbol],
+          disabled: T::Boolean,
+          frequency: Courier::DigestFrequency::OrSymbol,
+          is_default: T::Boolean,
+          time: String,
+          timezone: String,
+          updated: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The schedule's identifier, assigned by the server. This is the value the
+        # `/digests/schedules/{schedule_id}` endpoints are keyed by.
+        schedule_id:,
+        # ISO-8601 timestamp of when the schedule was created.
+        created: nil,
+        # Day of the month, 1-31.
+        day_of_month: nil,
+        # A day of the week. Accepted case-insensitively, returned lowercase.
+        day_of_week: nil,
+        days_of_week: nil,
+        # Whether the schedule is disabled.
+        disabled: nil,
+        # Omitted for a stored schedule this enum cannot express. Those schedules never
+        # fire, but their `schedule_id` is still returned so the `/digests/*` endpoints
+        # remain reachable for them.
+        frequency: nil,
+        # Whether this is the schedule recipients are placed on by default.
+        is_default: nil,
+        # 24-hour local delivery time, `HH:MM`.
+        time: nil,
+        # IANA timezone the schedule is expressed in. Absent means UTC.
+        timezone: nil,
+        # ISO-8601 timestamp of the last update.
+        updated: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            schedule_id: String,
+            created: String,
+            day_of_month: Integer,
+            day_of_week: Courier::DigestDayOfWeek::TaggedSymbol,
+            days_of_week: T::Array[Courier::DigestDayOfWeek::TaggedSymbol],
+            disabled: T::Boolean,
+            frequency: Courier::DigestFrequency::TaggedSymbol,
+            is_default: T::Boolean,
+            time: String,
+            timezone: String,
+            updated: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/courier/models/users/preference_update_or_create_topic_params.rbi

@@ -96,6 +96,14 @@ module Courier
           end
           attr_accessor :custom_routing
 
+          # Put this recipient on one of the topic's digest schedules. Send `null` to clear
+          # the choice and return them to the topic's default. Omit to leave an existing
+          # choice alone, unlike the routing fields, which this endpoint replaces. An id
+          # that is not an active schedule on the topic is rejected with a `400` before
+          # anything is written.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :digest_schedule_id
+
           # Set to true to route this topic to the channels in custom_routing instead of the
           # topic's default routing.
           sig { returns(T.nilable(T::Boolean)) }
@@ -106,6 +114,7 @@ module Courier
               status: Courier::PreferenceStatus::OrSymbol,
               custom_routing:
                 T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
+              digest_schedule_id: T.nilable(String),
               has_custom_routing: T.nilable(T::Boolean)
             ).returns(T.attached_class)
           end
@@ -117,6 +126,12 @@ module Courier
             # The channels to deliver this topic on when has_custom_routing is true. One or
             # more of: direct_message, email, push, sms, webhook, inbox.
             custom_routing: nil,
+            # Put this recipient on one of the topic's digest schedules. Send `null` to clear
+            # the choice and return them to the topic's default. Omit to leave an existing
+            # choice alone, unlike the routing fields, which this endpoint replaces. An id
+            # that is not an active schedule on the topic is rejected with a `400` before
+            # anything is written.
+            digest_schedule_id: nil,
             # Set to true to route this topic to the channels in custom_routing instead of the
             # topic's default routing.
             has_custom_routing: nil
@@ -129,6 +144,7 @@ module Courier
                 status: Courier::PreferenceStatus::OrSymbol,
                 custom_routing:
                   T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
+                digest_schedule_id: T.nilable(String),
                 has_custom_routing: T.nilable(T::Boolean)
               }
             )

data/rbi/courier/models/users/topic_preference.rbi

@@ -38,6 +38,16 @@ module Courier
         end
         attr_accessor :custom_routing
 
+        # The digest schedule this recipient is on for the topic. Omitted rather than null
+        # when they have not chosen one, in which case the topic's default schedule
+        # applies. Ids come from the topic's digest configuration or from
+        # `GET /digests/schedules`.
+        sig { returns(T.nilable(String)) }
+        attr_reader :digest_schedule_id
+
+        sig { params(digest_schedule_id: String).void }
+        attr_writer :digest_schedule_id
+
         # Whether the user has chosen specific delivery channels for this topic (listed in
         # custom_routing) rather than the topic's default routing.
         sig { returns(T.nilable(T::Boolean)) }
@@ -69,6 +79,7 @@ module Courier
             topic_name: String,
             custom_routing:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
+            digest_schedule_id: String,
             has_custom_routing: T.nilable(T::Boolean),
             section_id: String,
             section_name: String
@@ -90,6 +101,11 @@ module Courier
           # has_custom_routing is true. One or more of: direct_message, email, push, sms,
           # webhook, inbox.
           custom_routing: nil,
+          # The digest schedule this recipient is on for the topic. Omitted rather than null
+          # when they have not chosen one, in which case the topic's default schedule
+          # applies. Ids come from the topic's digest configuration or from
+          # `GET /digests/schedules`.
+          digest_schedule_id: nil,
           # Whether the user has chosen specific delivery channels for this topic (listed in
           # custom_routing) rather than the topic's default routing.
           has_custom_routing: nil,
@@ -115,6 +131,7 @@ module Courier
                 T.nilable(
                   T::Array[Courier::ChannelClassification::TaggedSymbol]
                 ),
+              digest_schedule_id: String,
               has_custom_routing: T.nilable(T::Boolean),
               section_id: String,
               section_name: String

data/rbi/courier/models/workspace_preference_topic_create_request.rbi

@@ -40,6 +40,21 @@ module Courier
       sig { returns(T.nilable(String)) }
       attr_accessor :description
 
+      # A topic's digest configuration: the template that renders it, the cadences it
+      # delivers on, and how collected events are retained.
+      #
+      # Send `null` for the whole object to turn a digest off, which unlinks the
+      # template and removes its schedules. There is no `enabled` flag, and
+      # `schedules: []` is rejected, because both states are un-deliverable rather than
+      # merely off.
+      sig { returns(T.nilable(Courier::TopicDigestRequest)) }
+      attr_reader :digest
+
+      sig do
+        params(digest: T.nilable(Courier::TopicDigestRequest::OrHash)).void
+      end
+      attr_writer :digest
+
       # Whether to include a list-unsubscribe header on emails for this topic.
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :include_unsubscribe_header
@@ -67,6 +82,7 @@ module Courier
               ]
             ),
           description: T.nilable(String),
+          digest: T.nilable(Courier::TopicDigestRequest::OrHash),
           include_unsubscribe_header: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
@@ -83,6 +99,14 @@ module Courier
         allowed_preferences: nil,
         # Optional description shown under the topic on the hosted preferences page.
         description: nil,
+        # A topic's digest configuration: the template that renders it, the cadences it
+        # delivers on, and how collected events are retained.
+        #
+        # Send `null` for the whole object to turn a digest off, which unlinks the
+        # template and removes its schedules. There is no `enabled` flag, and
+        # `schedules: []` is rejected, because both states are un-deliverable rather than
+        # merely off.
+        digest: nil,
         # Whether to include a list-unsubscribe header on emails for this topic.
         include_unsubscribe_header: nil,
         # Default channels delivered for this topic. Defaults to empty if omitted.
@@ -105,6 +129,7 @@ module Courier
                 ]
               ),
             description: T.nilable(String),
+            digest: T.nilable(Courier::TopicDigestRequest),
             include_unsubscribe_header: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),

data/rbi/courier/models/workspace_preference_topic_get_response.rbi

@@ -65,6 +65,15 @@ module Courier
       sig { returns(T.nilable(String)) }
       attr_accessor :description
 
+      # A topic's digest configuration.
+      sig { returns(T.nilable(Courier::TopicDigestResponse)) }
+      attr_reader :digest
+
+      sig do
+        params(digest: T.nilable(Courier::TopicDigestResponse::OrHash)).void
+      end
+      attr_writer :digest
+
       # Id of the last updater.
       sig { returns(T.nilable(String)) }
       attr_accessor :updater
@@ -87,6 +96,7 @@ module Courier
           updated: String,
           creator: T.nilable(String),
           description: T.nilable(String),
+          digest: T.nilable(Courier::TopicDigestResponse::OrHash),
           updater: T.nilable(String)
         ).returns(T.attached_class)
       end
@@ -113,6 +123,8 @@ module Courier
         creator: nil,
         # Optional description shown under the topic on the hosted preferences page.
         description: nil,
+        # A topic's digest configuration.
+        digest: nil,
         # Id of the last updater.
         updater: nil
       )
@@ -137,6 +149,7 @@ module Courier
             updated: String,
             creator: T.nilable(String),
             description: T.nilable(String),
+            digest: T.nilable(Courier::TopicDigestResponse),
             updater: T.nilable(String)
           }
         )