trycourier 6.4.4 → 6.6.0

data/lib/courier.rb

@@ -94,6 +94,7 @@ require_relative "courier/models/workspace_preference_create_request"
 require_relative "courier/models/publish_preferences_request"
 require_relative "courier/models/workspace_preference_replace_request"
 require_relative "courier/models/workspace_preference_topic_create_request"
+require_relative "courier/models/topic_digest_release_request"
 require_relative "courier/models/workspace_preference_topic_replace_request"
 require_relative "courier/models/airship_profile"
 require_relative "courier/models/airship_profile_audience"
@@ -175,6 +176,8 @@ require_relative "courier/models/check"
 require_relative "courier/models/default_preferences"
 require_relative "courier/models/device_type"
 require_relative "courier/models/digest_category"
+require_relative "courier/models/digest_day_of_week"
+require_relative "courier/models/digest_frequency"
 require_relative "courier/models/digest_instance"
 require_relative "courier/models/digest_instance_list_response"
 require_relative "courier/models/digests/schedule_list_instances_params"
@@ -421,6 +424,11 @@ require_relative "courier/models/tenant_update_params"
 require_relative "courier/models/text_style"
 require_relative "courier/models/timeouts"
 require_relative "courier/models/token"
+require_relative "courier/models/topic_digest_category"
+require_relative "courier/models/topic_digest_request"
+require_relative "courier/models/topic_digest_response"
+require_relative "courier/models/topic_digest_schedule_request"
+require_relative "courier/models/topic_digest_schedule_response"
 require_relative "courier/models/translation_retrieve_params"
 require_relative "courier/models/translation_retrieve_response"
 require_relative "courier/models/translation_update_params"
@@ -473,7 +481,9 @@ require_relative "courier/models/workspace_preference_replace_params"
 require_relative "courier/models/workspace_preference_retrieve_params"
 require_relative "courier/models/workspace_preferences/topic_archive_params"
 require_relative "courier/models/workspace_preferences/topic_create_params"
+require_relative "courier/models/workspace_preferences/topic_delete_digest_params"
 require_relative "courier/models/workspace_preferences/topic_list_params"
+require_relative "courier/models/workspace_preferences/topic_release_digest_params"
 require_relative "courier/models/workspace_preferences/topic_replace_params"
 require_relative "courier/models/workspace_preferences/topic_retrieve_params"
 require_relative "courier/models/workspace_preference_topic_get_response"

data/rbi/courier/models/digest_day_of_week.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Courier
+  module Models
+    # A day of the week. Accepted case-insensitively, returned lowercase.
+    module DigestDayOfWeek
+      extend Courier::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Courier::DigestDayOfWeek) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      SUNDAY = T.let(:sunday, Courier::DigestDayOfWeek::TaggedSymbol)
+      MONDAY = T.let(:monday, Courier::DigestDayOfWeek::TaggedSymbol)
+      TUESDAY = T.let(:tuesday, Courier::DigestDayOfWeek::TaggedSymbol)
+      WEDNESDAY = T.let(:wednesday, Courier::DigestDayOfWeek::TaggedSymbol)
+      THURSDAY = T.let(:thursday, Courier::DigestDayOfWeek::TaggedSymbol)
+      FRIDAY = T.let(:friday, Courier::DigestDayOfWeek::TaggedSymbol)
+      SATURDAY = T.let(:saturday, Courier::DigestDayOfWeek::TaggedSymbol)
+
+      sig { override.returns(T::Array[Courier::DigestDayOfWeek::TaggedSymbol]) }
+      def self.values
+      end
+    end
+  end
+end

data/rbi/courier/models/digest_frequency.rbi

@@ -0,0 +1,25 @@
+# typed: strong
+
+module Courier
+  module Models
+    # How often a digest is delivered. `instant` delivers immediately without
+    # batching, and is the one value that takes no `time`.
+    module DigestFrequency
+      extend Courier::Internal::Type::Enum
+
+      TaggedSymbol = T.type_alias { T.all(Symbol, Courier::DigestFrequency) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      INSTANT = T.let(:instant, Courier::DigestFrequency::TaggedSymbol)
+      DAILY = T.let(:daily, Courier::DigestFrequency::TaggedSymbol)
+      WEEKDAYS = T.let(:weekdays, Courier::DigestFrequency::TaggedSymbol)
+      WEEKLY = T.let(:weekly, Courier::DigestFrequency::TaggedSymbol)
+      CUSTOM_DAYS = T.let(:custom_days, Courier::DigestFrequency::TaggedSymbol)
+      MONTHLY = T.let(:monthly, Courier::DigestFrequency::TaggedSymbol)
+
+      sig { override.returns(T::Array[Courier::DigestFrequency::TaggedSymbol]) }
+      def self.values
+      end
+    end
+  end
+end

data/rbi/courier/models/email_footer.rbi

@@ -6,28 +6,250 @@ module Courier
       OrHash =
         T.type_alias { T.any(Courier::EmailFooter, Courier::Internal::AnyHash) }
 
-      sig { returns(T.nilable(String)) }
-      attr_accessor :content
-
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :inherit_default
 
+      # The footer body, as markdown. This is the field the API returns and accepts; it
+      # is omitted entirely when no footer body is set. Sending null is accepted and
+      # treated as no footer body.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :markdown
+
+      # Social links rendered in the email footer.
+      sig { returns(T.nilable(Courier::EmailFooter::Social)) }
+      attr_reader :social
+
+      sig do
+        params(social: T.nilable(Courier::EmailFooter::Social::OrHash)).void
+      end
+      attr_writer :social
+
       sig do
         params(
-          content: T.nilable(String),
-          inherit_default: T.nilable(T::Boolean)
+          inherit_default: T.nilable(T::Boolean),
+          markdown: T.nilable(String),
+          social: T.nilable(Courier::EmailFooter::Social::OrHash)
         ).returns(T.attached_class)
       end
-      def self.new(content: nil, inherit_default: nil)
+      def self.new(
+        inherit_default: nil,
+        # The footer body, as markdown. This is the field the API returns and accepts; it
+        # is omitted entirely when no footer body is set. Sending null is accepted and
+        # treated as no footer body.
+        markdown: nil,
+        # Social links rendered in the email footer.
+        social: nil
+      )
       end
 
       sig do
         override.returns(
-          { content: T.nilable(String), inherit_default: T.nilable(T::Boolean) }
+          {
+            inherit_default: T.nilable(T::Boolean),
+            markdown: T.nilable(String),
+            social: T.nilable(Courier::EmailFooter::Social)
+          }
         )
       end
       def to_hash
       end
+
+      class Social < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(Courier::EmailFooter::Social, Courier::Internal::AnyHash)
+          end
+
+        sig { returns(T.nilable(Courier::EmailFooter::Social::Facebook)) }
+        attr_reader :facebook
+
+        sig do
+          params(
+            facebook: T.nilable(Courier::EmailFooter::Social::Facebook::OrHash)
+          ).void
+        end
+        attr_writer :facebook
+
+        sig { returns(T.nilable(Courier::EmailFooter::Social::Instagram)) }
+        attr_reader :instagram
+
+        sig do
+          params(
+            instagram:
+              T.nilable(Courier::EmailFooter::Social::Instagram::OrHash)
+          ).void
+        end
+        attr_writer :instagram
+
+        sig { returns(T.nilable(Courier::EmailFooter::Social::Linkedin)) }
+        attr_reader :linkedin
+
+        sig do
+          params(
+            linkedin: T.nilable(Courier::EmailFooter::Social::Linkedin::OrHash)
+          ).void
+        end
+        attr_writer :linkedin
+
+        sig { returns(T.nilable(Courier::EmailFooter::Social::Medium)) }
+        attr_reader :medium
+
+        sig do
+          params(
+            medium: T.nilable(Courier::EmailFooter::Social::Medium::OrHash)
+          ).void
+        end
+        attr_writer :medium
+
+        sig { returns(T.nilable(Courier::EmailFooter::Social::Twitter)) }
+        attr_reader :twitter
+
+        sig do
+          params(
+            twitter: T.nilable(Courier::EmailFooter::Social::Twitter::OrHash)
+          ).void
+        end
+        attr_writer :twitter
+
+        # Social links rendered in the email footer.
+        sig do
+          params(
+            facebook: T.nilable(Courier::EmailFooter::Social::Facebook::OrHash),
+            instagram:
+              T.nilable(Courier::EmailFooter::Social::Instagram::OrHash),
+            linkedin: T.nilable(Courier::EmailFooter::Social::Linkedin::OrHash),
+            medium: T.nilable(Courier::EmailFooter::Social::Medium::OrHash),
+            twitter: T.nilable(Courier::EmailFooter::Social::Twitter::OrHash)
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          facebook: nil,
+          instagram: nil,
+          linkedin: nil,
+          medium: nil,
+          twitter: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              facebook: T.nilable(Courier::EmailFooter::Social::Facebook),
+              instagram: T.nilable(Courier::EmailFooter::Social::Instagram),
+              linkedin: T.nilable(Courier::EmailFooter::Social::Linkedin),
+              medium: T.nilable(Courier::EmailFooter::Social::Medium),
+              twitter: T.nilable(Courier::EmailFooter::Social::Twitter)
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Facebook < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::EmailFooter::Social::Facebook,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :url
+
+          sig { params(url: T.nilable(String)).returns(T.attached_class) }
+          def self.new(url: nil)
+          end
+
+          sig { override.returns({ url: T.nilable(String) }) }
+          def to_hash
+          end
+        end
+
+        class Instagram < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::EmailFooter::Social::Instagram,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :url
+
+          sig { params(url: T.nilable(String)).returns(T.attached_class) }
+          def self.new(url: nil)
+          end
+
+          sig { override.returns({ url: T.nilable(String) }) }
+          def to_hash
+          end
+        end
+
+        class Linkedin < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::EmailFooter::Social::Linkedin,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :url
+
+          sig { params(url: T.nilable(String)).returns(T.attached_class) }
+          def self.new(url: nil)
+          end
+
+          sig { override.returns({ url: T.nilable(String) }) }
+          def to_hash
+          end
+        end
+
+        class Medium < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::EmailFooter::Social::Medium,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :url
+
+          sig { params(url: T.nilable(String)).returns(T.attached_class) }
+          def self.new(url: nil)
+          end
+
+          sig { override.returns({ url: T.nilable(String) }) }
+          def to_hash
+          end
+        end
+
+        class Twitter < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::EmailFooter::Social::Twitter,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :url
+
+          sig { params(url: T.nilable(String)).returns(T.attached_class) }
+          def self.new(url: nil)
+          end
+
+          sig { override.returns({ url: T.nilable(String) }) }
+          def to_hash
+          end
+        end
+      end
     end
   end
 end

data/rbi/courier/models/journey_node.rbi

@@ -398,7 +398,18 @@ module Courier
 
         # Add the current event to a digest keyed by the given subscription topic. The
         # digest accumulates events and releases them on the schedule configured for the
-        # topic.
+        # topic, using the notification template configured on that topic. This node's
+        # `type` value is `add-to-digest`.
+        #
+        # **The topic must have a template configured.** If the topic has no template when
+        # the first event reaches this node, the journey run fails immediately: the run is
+        # marked `ERROR`, no digest instance is created, and the journey does not continue
+        # past this node. Configure the topic's template before using the topic in a
+        # journey.
+        #
+        # If the journey run is scoped to a tenant, digests are kept separate per tenant:
+        # two runs for the same user under different tenants accumulate and release as
+        # separate digests, even on the same topic.
         sig do
           params(
             subscription_topic_id: String,

data/rbi/courier/models/topic_digest_category.rbi

@@ -0,0 +1,116 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestCategory < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::TopicDigestCategory, Courier::Internal::AnyHash)
+        end
+
+      # The key that identifies the category within the digest.
+      sig { returns(String) }
+      attr_accessor :category_key
+
+      # How many collected events are carried into the rendered digest. Defaults to 10.
+      #
+      # Events beyond the limit are discarded, not held back for the next digest: the
+      # release consumes everything collected so far and only `limit` of them appear.
+      # `retain` decides which ones those are.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :limit
+
+      sig { params(limit: Integer).void }
+      attr_writer :limit
+
+      # Which collected events survive the `limit`. `FIRST` and `LOWEST` keep the
+      # earliest or smallest; `LAST` and `HIGHEST` keep the latest or largest. Accepted
+      # case-insensitively, returned uppercase.
+      sig { returns(T.nilable(Courier::TopicDigestCategory::Retain::OrSymbol)) }
+      attr_reader :retain
+
+      sig do
+        params(retain: Courier::TopicDigestCategory::Retain::OrSymbol).void
+      end
+      attr_writer :retain
+
+      # The data key used to rank events. Required when `retain` is `HIGHEST` or
+      # `LOWEST`.
+      sig { returns(T.nilable(String)) }
+      attr_reader :sort_key
+
+      sig { params(sort_key: String).void }
+      attr_writer :sort_key
+
+      # How events collected under a category key are retained when a digest holds more
+      # than it will render.
+      sig do
+        params(
+          category_key: String,
+          limit: Integer,
+          retain: Courier::TopicDigestCategory::Retain::OrSymbol,
+          sort_key: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The key that identifies the category within the digest.
+        category_key:,
+        # How many collected events are carried into the rendered digest. Defaults to 10.
+        #
+        # Events beyond the limit are discarded, not held back for the next digest: the
+        # release consumes everything collected so far and only `limit` of them appear.
+        # `retain` decides which ones those are.
+        limit: nil,
+        # Which collected events survive the `limit`. `FIRST` and `LOWEST` keep the
+        # earliest or smallest; `LAST` and `HIGHEST` keep the latest or largest. Accepted
+        # case-insensitively, returned uppercase.
+        retain: nil,
+        # The data key used to rank events. Required when `retain` is `HIGHEST` or
+        # `LOWEST`.
+        sort_key: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            category_key: String,
+            limit: Integer,
+            retain: Courier::TopicDigestCategory::Retain::OrSymbol,
+            sort_key: String
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Which collected events survive the `limit`. `FIRST` and `LOWEST` keep the
+      # earliest or smallest; `LAST` and `HIGHEST` keep the latest or largest. Accepted
+      # case-insensitively, returned uppercase.
+      module Retain
+        extend Courier::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Courier::TopicDigestCategory::Retain) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        FIRST =
+          T.let(:FIRST, Courier::TopicDigestCategory::Retain::TaggedSymbol)
+        LAST = T.let(:LAST, Courier::TopicDigestCategory::Retain::TaggedSymbol)
+        HIGHEST =
+          T.let(:HIGHEST, Courier::TopicDigestCategory::Retain::TaggedSymbol)
+        LOWEST =
+          T.let(:LOWEST, Courier::TopicDigestCategory::Retain::TaggedSymbol)
+        NONE = T.let(:NONE, Courier::TopicDigestCategory::Retain::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Courier::TopicDigestCategory::Retain::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/topic_digest_release_request.rbi

@@ -0,0 +1,51 @@
+# typed: strong
+
+module Courier
+  module Models
+    class TopicDigestReleaseRequest < Courier::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Courier::TopicDigestReleaseRequest, Courier::Internal::AnyHash)
+        end
+
+      # The recipient whose digest to release. Required: there is no "release everyone
+      # on this topic" form, because a whole-schedule flush already has its own endpoint
+      # and a body-shaped difference between one recipient and all of them is too easy
+      # to get wrong.
+      sig { returns(String) }
+      attr_accessor :user_id
+
+      # The recipient's tenant, when they were sent to as part of one -- the same value
+      # returned as `tenant_id` on a digest instance and sent as
+      # `message.context.tenant_id`. It is part of the held digest's key, so a tenanted
+      # recipient cannot be found without it. Omit for an ordinary recipient.
+      sig { returns(T.nilable(String)) }
+      attr_reader :tenant_id
+
+      sig { params(tenant_id: String).void }
+      attr_writer :tenant_id
+
+      # Which recipient's held digest to release.
+      sig do
+        params(user_id: String, tenant_id: String).returns(T.attached_class)
+      end
+      def self.new(
+        # The recipient whose digest to release. Required: there is no "release everyone
+        # on this topic" form, because a whole-schedule flush already has its own endpoint
+        # and a body-shaped difference between one recipient and all of them is too easy
+        # to get wrong.
+        user_id:,
+        # The recipient's tenant, when they were sent to as part of one -- the same value
+        # returned as `tenant_id` on a digest instance and sent as
+        # `message.context.tenant_id`. It is part of the held digest's key, so a tenanted
+        # recipient cannot be found without it. Omit for an ordinary recipient.
+        tenant_id: nil
+      )
+      end
+
+      sig { override.returns({ user_id: String, tenant_id: String }) }
+      def to_hash
+      end
+    end
+  end
+end

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