trycourier 6.5.0 → 6.7.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/create_journey_request.rbi

@@ -37,6 +37,17 @@ module Courier
       end
       attr_accessor :nodes
 
+      # Cancelation token stored on the journey definition. It tags every run the
+      # journey creates so that `POST /journeys/cancel` can later cancel those runs by
+      # token. Accepts a templated string such as `order-{{data.order_id}}`, which is
+      # resolved per run when the journey is invoked. On a replace, omitting this field
+      # preserves any existing token and sending a value replaces it.
+      sig { returns(T.nilable(String)) }
+      attr_reader :cancelation_token
+
+      sig { params(cancelation_token: String).void }
+      attr_writer :cancelation_token
+
       sig { returns(T.nilable(T::Boolean)) }
       attr_reader :enabled
 
@@ -75,6 +86,7 @@ module Courier
                 Courier::JourneyNode::JourneyBranchNode::OrHash
               )
             ],
+          cancelation_token: String,
           enabled: T::Boolean,
           state: Courier::JourneyState::OrSymbol
         ).returns(T.attached_class)
@@ -82,6 +94,12 @@ module Courier
       def self.new(
         name:,
         nodes:,
+        # Cancelation token stored on the journey definition. It tags every run the
+        # journey creates so that `POST /journeys/cancel` can later cancel those runs by
+        # token. Accepts a templated string such as `order-{{data.order_id}}`, which is
+        # resolved per run when the journey is invoked. On a replace, omitting this field
+        # preserves any existing token and sending a value replaces it.
+        cancelation_token: nil,
         enabled: nil,
         # Lifecycle state of a journey.
         state: nil
@@ -113,6 +131,7 @@ module Courier
                   Courier::JourneyNode::JourneyBranchNode
                 )
               ],
+            cancelation_token: String,
             enabled: T::Boolean,
             state: Courier::JourneyState::OrSymbol
           }

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/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/journey_response.rbi

@@ -11,6 +11,12 @@ module Courier
       sig { returns(String) }
       attr_accessor :id
 
+      # The journey cancelation token, or null when none is set. A token authored in the
+      # dashboard is returned in its raw templated form, such as
+      # `order-{{data.order_id}}`, so it can be read back and asserted.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :cancelation_token
+
       sig { returns(T.nilable(Integer)) }
       attr_accessor :created
 
@@ -43,6 +49,7 @@ module Courier
       sig do
         params(
           id: String,
+          cancelation_token: T.nilable(String),
           created: T.nilable(Integer),
           creator: T.nilable(String),
           enabled: T::Boolean,
@@ -76,6 +83,10 @@ module Courier
       end
       def self.new(
         id:,
+        # The journey cancelation token, or null when none is set. A token authored in the
+        # dashboard is returned in its raw templated form, such as
+        # `order-{{data.order_id}}`, so it can be read back and asserted.
+        cancelation_token:,
         created:,
         creator:,
         enabled:,
@@ -93,6 +104,7 @@ module Courier
         override.returns(
           {
             id: String,
+            cancelation_token: T.nilable(String),
             created: T.nilable(Integer),
             creator: T.nilable(String),
             enabled: T::Boolean,

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,126 @@
+# 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 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
+
+      # The cadences this digest delivers on.
+      #
+      # The array replaces the stored schedules wholesale, so a schedule you leave out
+      # of it is deleted along with its delivery rule. Omit the key entirely to leave
+      # the stored schedules untouched — useful for changing `template_id` or
+      # `categories` without restating every schedule.
+      #
+      # A digest must end up with at least one schedule, because one with none collects
+      # events into an instance that can never fire. So sending `[]` is always a `400`,
+      # and so is omitting the key on a topic that has no schedules stored yet.
+      #
+      # On **create** the key is required outright: a topic being created has nothing
+      # stored to leave alone, and the topic row is written before its digest, so
+      # rejecting it any later would leave the topic behind and let a retry duplicate
+      # it.
+      sig { returns(T.nilable(T::Array[Courier::TopicDigestScheduleRequest])) }
+      attr_reader :schedules
+
+      sig do
+        params(
+          schedules: T::Array[Courier::TopicDigestScheduleRequest::OrHash]
+        ).void
+      end
+      attr_writer :schedules
+
+      # 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(
+          template_id: String,
+          audience_id: String,
+          categories: T::Array[Courier::TopicDigestCategory::OrHash],
+          schedules: T::Array[Courier::TopicDigestScheduleRequest::OrHash],
+          trigger_empty: T::Boolean
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # 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,
+        # The cadences this digest delivers on.
+        #
+        # The array replaces the stored schedules wholesale, so a schedule you leave out
+        # of it is deleted along with its delivery rule. Omit the key entirely to leave
+        # the stored schedules untouched — useful for changing `template_id` or
+        # `categories` without restating every schedule.
+        #
+        # A digest must end up with at least one schedule, because one with none collects
+        # events into an instance that can never fire. So sending `[]` is always a `400`,
+        # and so is omitting the key on a topic that has no schedules stored yet.
+        #
+        # On **create** the key is required outright: a topic being created has nothing
+        # stored to leave alone, and the topic row is written before its digest, so
+        # rejecting it any later would leave the topic behind and let a retry duplicate
+        # it.
+        schedules: nil,
+        # Whether to deliver the digest even when nothing was collected.
+        trigger_empty: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            template_id: String,
+            audience_id: String,
+            categories: T::Array[Courier::TopicDigestCategory],
+            schedules: T::Array[Courier::TopicDigestScheduleRequest],
+            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