trycourier 4.21.0 → 4.23.0

data/rbi/courier/resources/users/tokens.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Users
+      # Register and manage the APNS and FCM device tokens Courier delivers push
+      # notifications to.
       class Tokens
-        # Get single token available for a `:token`
+        # Returns one device token with its provider key, status and status reason, expiry
+        # date, and any properties stored alongside it.
         sig do
           params(
             token: String,
@@ -21,7 +24,8 @@ module Courier
         )
         end
 
-        # Apply a JSON Patch (RFC 6902) to the specified token.
+        # Applies a JSON Patch to a device token, changing its status, expiry, or
+        # properties without re-registering it.
         sig do
           params(
             token: String,
@@ -41,7 +45,8 @@ module Courier
         )
         end
 
-        # Gets all tokens available for a :user_id
+        # Returns every device token registered for a user, each with its provider key,
+        # status, and expiry date.
         sig do
           params(
             user_id: String,
@@ -55,7 +60,8 @@ module Courier
         )
         end
 
-        # Delete User Token
+        # Deletes one device token for a user, addressed by the token value, so push sends
+        # no longer target that device.
         sig do
           params(
             token: String,
@@ -72,7 +78,8 @@ module Courier
         )
         end
 
-        # Adds multiple tokens to a user and overwrites matching existing tokens.
+        # Registers several device tokens for a user in one call, overwriting any stored
+        # token with a matching value.
         sig do
           params(
             user_id: String,
@@ -86,7 +93,8 @@ module Courier
         )
         end
 
-        # Adds a single token to a user and overwrites a matching existing token.
+        # Registers one device token for a user against a provider key, overwriting the
+        # token if it already exists. Push sends resolve tokens per user.
         sig do
           params(
             token: String,

data/rbi/courier/resources/users.rbi

@@ -3,12 +3,18 @@
 module Courier
   module Resources
     class Users
+      # Read and write a single user's notification preferences, per topic and per
+      # channel.
       sig { returns(Courier::Resources::Users::Preferences) }
       attr_reader :preferences
 
+      # Associate a user with one or more tenants, and read or remove those
+      # associations.
       sig { returns(Courier::Resources::Users::Tenants) }
       attr_reader :tenants
 
+      # Register and manage the APNS and FCM device tokens Courier delivers push
+      # notifications to.
       sig { returns(Courier::Resources::Users::Tokens) }
       attr_reader :tokens
 

data/rbi/courier/resources/workspace_preferences/topics.rbi

@@ -3,10 +3,11 @@
 module Courier
   module Resources
     class WorkspacePreferences
+      # Manage the workspace catalog of subscription topics, the sections that group
+      # them, and publishing the preference page.
       class Topics
-        # Create a subscription preference topic inside a workspace preference. Fails with
-        # 404 if the workspace preference does not exist. The topic id is generated and
-        # returned.
+        # Creates a subscription topic inside a workspace preference. The default status
+        # sets whether users start opted in, opted out, or required.
         sig do
           params(
             section_id: String,
@@ -24,34 +25,51 @@ module Courier
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
             topic_data: T.nilable(T::Hash[Symbol, T.anything]),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::WorkspacePreferenceTopicGetResponse)
         end
         def create(
-          # Id of the workspace preference to create the topic in.
+          # Path param: Id of the workspace preference to create the topic in.
           section_id,
-          # The default subscription status applied when a recipient has not set their own.
+          # Body param: The default subscription status applied when a recipient has not set
+          # their own.
           default_status:,
-          # Human-readable name for the preference topic.
+          # Body param: Human-readable name for the preference topic.
           name:,
-          # Preference controls a recipient may customize for this topic. Defaults to empty
-          # if omitted.
+          # Body param: Preference controls a recipient may customize for this topic.
+          # Defaults to empty if omitted.
           allowed_preferences: nil,
-          # Optional description shown under the topic on the hosted preferences page.
+          # Body param: Optional description shown under the topic on the hosted preferences
+          # page.
           description: nil,
-          # Whether to include a list-unsubscribe header on emails for this topic.
+          # Body param: 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.
+          # Body param: Default channels delivered for this topic. Defaults to empty if
+          # omitted.
           routing_options: nil,
-          # Arbitrary metadata associated with the topic.
+          # Body param: Arbitrary metadata associated with the topic.
           topic_data: nil,
+          # Header param: A unique key that makes this request idempotent. If Courier
+          # receives another request with the same `Idempotency-Key`, it returns the stored
+          # response from the first request without performing the operation again
+          # (including the original status code and any error). Use it to safely retry
+          # `POST` requests after network failures without risking duplicate sends. The key
+          # is scoped to this endpoint.
+          idempotency_key: nil,
+          # Header param: How long the idempotency key remains valid, as a Unix epoch
+          # timestamp in seconds or an ISO 8601 date string. Only applies when
+          # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+          # maximum is 1 year.
+          x_idempotency_expiration: nil,
           request_options: {}
         )
         end
 
-        # Retrieve a topic within a workspace preference. Returns 404 if the workspace
-        # preference does not exist, the topic does not exist, or the topic belongs to a
-        # different workspace preference.
+        # Returns one subscription topic with its default status, routing options, allowed
+        # preferences, and unsubscribe header setting.
         sig do
           params(
             topic_id: String,
@@ -68,7 +86,8 @@ module Courier
         )
         end
 
-        # List the topics in a workspace preference.
+        # Returns the subscription topics inside a workspace preference, each with its
+        # default status and routing options.
         sig do
           params(
             section_id: String,
@@ -82,8 +101,8 @@ module Courier
         )
         end
 
-        # Archive a topic and remove it from its workspace preference. Same 404 rules as
-        # GET.
+        # Archives a subscription topic and removes it from its workspace preference,
+        # addressed by section id and topic id.
         sig do
           params(
             topic_id: String,

data/rbi/courier/resources/workspace_preferences.rbi

@@ -2,13 +2,16 @@
 
 module Courier
   module Resources
+    # Manage the workspace catalog of subscription topics, the sections that group
+    # them, and publishing the preference page.
     class WorkspacePreferences
+      # Manage the workspace catalog of subscription topics, the sections that group
+      # them, and publishing the preference page.
       sig { returns(Courier::Resources::WorkspacePreferences::Topics) }
       attr_reader :topics
 
-      # Create a workspace preference. The workspace preference id is generated and
-      # returned. Topics are created inside a workspace preference via POST
-      # /preferences/sections/{section_id}/topics.
+      # Creates a workspace preference and returns its generated id. Add subscription
+      # topics to it afterwards with the topics endpoint.
       sig do
         params(
           name: String,
@@ -16,23 +19,41 @@ module Courier
           has_custom_routing: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::WorkspacePreferenceGetResponse)
       end
       def create(
-        # Human-readable name for the workspace preference.
+        # Body param: Human-readable name for the workspace preference.
         name:,
-        # Optional description shown under the section on the hosted preferences page.
+        # Body param: Optional description shown under the section on the hosted
+        # preferences page.
         description: nil,
-        # Whether the workspace preference defines custom routing for its topics.
+        # Body param: Whether the workspace preference defines custom routing for its
+        # topics.
         has_custom_routing: nil,
-        # Default channels for the workspace preference. Defaults to empty if omitted.
+        # Body param: Default channels for the workspace preference. Defaults to empty if
+        # omitted.
         routing_options: nil,
+        # Header param: A unique key that makes this request idempotent. If Courier
+        # receives another request with the same `Idempotency-Key`, it returns the stored
+        # response from the first request without performing the operation again
+        # (including the original status code and any error). Use it to safely retry
+        # `POST` requests after network failures without risking duplicate sends. The key
+        # is scoped to this endpoint.
+        idempotency_key: nil,
+        # Header param: How long the idempotency key remains valid, as a Unix epoch
+        # timestamp in seconds or an ISO 8601 date string. Only applies when
+        # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+        # maximum is 1 year.
+        x_idempotency_expiration: nil,
         request_options: {}
       )
       end
 
-      # Retrieve a workspace preference by id, including its topics.
+      # Returns one workspace preference by id, including its subscription topics,
+      # routing options, and custom routing flag.
       sig do
         params(
           section_id: String,
@@ -46,8 +67,8 @@ module Courier
       )
       end
 
-      # List the workspace's preferences. Each workspace preference embeds its topics.
-      # Scoped to the workspace of the API key.
+      # Returns the workspace's preferences, each embedding its subscription topics,
+      # routing options, and whether custom routing is allowed.
       sig do
         params(request_options: Courier::RequestOptions::OrHash).returns(
           Courier::WorkspacePreferenceListResponse
@@ -71,25 +92,38 @@ module Courier
       )
       end
 
-      # Publish the workspace's preferences page. Takes a snapshot of every workspace
-      # preference with its topics under a new published version, making the current
-      # state visible on the hosted preferences page (non-draft).
+      # Publishes the workspace preference page, snapshotting every preference and
+      # topic, and returns the page id and a preview URL.
       sig do
         params(
           brand_id: T.nilable(String),
           description: T.nilable(String),
           heading: T.nilable(String),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::PublishPreferencesResponse)
       end
       def publish(
-        # Brand for the hosted page - "default" (workspace default brand), "none" (no
-        # brand), or a specific brand id. Defaults to "default".
+        # Body param: Brand for the hosted page - "default" (workspace default brand),
+        # "none" (no brand), or a specific brand id. Defaults to "default".
         brand_id: nil,
-        # Description shown under the heading on the hosted preferences page.
+        # Body param: Description shown under the heading on the hosted preferences page.
         description: nil,
-        # Heading shown at the top of the hosted preferences page.
+        # Body param: Heading shown at the top of the hosted preferences page.
         heading: nil,
+        # Header param: A unique key that makes this request idempotent. If Courier
+        # receives another request with the same `Idempotency-Key`, it returns the stored
+        # response from the first request without performing the operation again
+        # (including the original status code and any error). Use it to safely retry
+        # `POST` requests after network failures without risking duplicate sends. The key
+        # is scoped to this endpoint.
+        idempotency_key: nil,
+        # Header param: How long the idempotency key remains valid, as a Unix epoch
+        # timestamp in seconds or an ISO 8601 date string. Only applies when
+        # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+        # maximum is 1 year.
+        x_idempotency_expiration: nil,
         request_options: {}
       )
       end

data/sig/courier/client.rbs

@@ -24,6 +24,8 @@ module Courier
 
     attr_reader journeys: Courier::Resources::Journeys
 
+    attr_reader broadcasts: Courier::Resources::Broadcasts
+
     attr_reader brands: Courier::Resources::Brands
 
     attr_reader digests: Courier::Resources::Digests
@@ -32,6 +34,8 @@ module Courier
 
     attr_reader lists: Courier::Resources::Lists
 
+    attr_reader inbox: Courier::Resources::Inbox
+
     attr_reader messages: Courier::Resources::Messages
 
     attr_reader requests: Courier::Resources::Requests

data/sig/courier/models/automations/invoke_invoke_ad_hoc_params.rbs

@@ -8,7 +8,9 @@ module Courier
           data: ::Hash[Symbol, top]?,
           profile: ::Hash[Symbol, top]?,
           recipient: String?,
-          template: String?
+          template: String?,
+          idempotency_key: String,
+          x_idempotency_expiration: String
         }
         & Courier::Internal::Type::request_parameters
 
@@ -28,6 +30,14 @@ module Courier
 
         attr_accessor template: String?
 
+        attr_reader idempotency_key: String?
+
+        def idempotency_key=: (String) -> String
+
+        attr_reader x_idempotency_expiration: String?
+
+        def x_idempotency_expiration=: (String) -> String
+
         def initialize: (
           automation: Courier::Automations::InvokeInvokeAdHocParams::Automation,
           ?brand: String?,
@@ -35,6 +45,8 @@ module Courier
           ?profile: ::Hash[Symbol, top]?,
           ?recipient: String?,
           ?template: String?,
+          ?idempotency_key: String,
+          ?x_idempotency_expiration: String,
           ?request_options: Courier::request_opts
         ) -> void
 
@@ -45,6 +57,8 @@ module Courier
           profile: ::Hash[Symbol, top]?,
           recipient: String?,
           template: String?,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions
         }
 

data/sig/courier/models/automations/invoke_invoke_by_template_params.rbs

@@ -8,7 +8,9 @@ module Courier
           brand: String?,
           data: ::Hash[Symbol, top]?,
           profile: ::Hash[Symbol, top]?,
-          template: String?
+          template: String?,
+          idempotency_key: String,
+          x_idempotency_expiration: String
         }
         & Courier::Internal::Type::request_parameters
 
@@ -28,6 +30,14 @@ module Courier
 
         attr_accessor template: String?
 
+        attr_reader idempotency_key: String?
+
+        def idempotency_key=: (String) -> String
+
+        attr_reader x_idempotency_expiration: String?
+
+        def x_idempotency_expiration=: (String) -> String
+
         def initialize: (
           template_id: String,
           recipient: String?,
@@ -35,6 +45,8 @@ module Courier
           ?data: ::Hash[Symbol, top]?,
           ?profile: ::Hash[Symbol, top]?,
           ?template: String?,
+          ?idempotency_key: String,
+          ?x_idempotency_expiration: String,
           ?request_options: Courier::request_opts
         ) -> void
 
@@ -45,6 +57,8 @@ module Courier
           data: ::Hash[Symbol, top]?,
           profile: ::Hash[Symbol, top]?,
           template: String?,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions
         }
       end

data/sig/courier/models/brand_create_params.rbs

@@ -5,7 +5,9 @@ module Courier
         name: String,
         settings: Courier::BrandSettings,
         id: String?,
-        snippets: Courier::BrandSnippets?
+        snippets: Courier::BrandSnippets?,
+        idempotency_key: String,
+        x_idempotency_expiration: String
       }
       & Courier::Internal::Type::request_parameters
 
@@ -21,11 +23,21 @@ module Courier
 
       attr_accessor snippets: Courier::BrandSnippets?
 
+      attr_reader idempotency_key: String?
+
+      def idempotency_key=: (String) -> String
+
+      attr_reader x_idempotency_expiration: String?
+
+      def x_idempotency_expiration=: (String) -> String
+
       def initialize: (
         name: String,
         settings: Courier::BrandSettings,
         ?id: String?,
         ?snippets: Courier::BrandSnippets?,
+        ?idempotency_key: String,
+        ?x_idempotency_expiration: String,
         ?request_options: Courier::request_opts
       ) -> void
 
@@ -34,6 +46,8 @@ module Courier
         settings: Courier::BrandSettings,
         id: String?,
         snippets: Courier::BrandSnippets?,
+        idempotency_key: String,
+        x_idempotency_expiration: String,
         request_options: Courier::RequestOptions
       }
     end

data/sig/courier/models/broadcast.rbs

@@ -0,0 +1,98 @@
+module Courier
+  module Models
+    type broadcast =
+      {
+        id: String,
+        channel: Courier::Models::Broadcast::channel,
+        created_at: String,
+        created_by: String,
+        name: String,
+        status: Courier::Models::Broadcast::status,
+        updated_at: String,
+        updated_by: String,
+        archived_at: String?,
+        archived_by: String?,
+        schedule: Courier::BroadcastSchedule?
+      }
+
+    class Broadcast < Courier::Internal::Type::BaseModel
+      attr_accessor id: String
+
+      attr_accessor channel: Courier::Models::Broadcast::channel
+
+      attr_accessor created_at: String
+
+      attr_accessor created_by: String
+
+      attr_accessor name: String
+
+      attr_accessor status: Courier::Models::Broadcast::status
+
+      attr_accessor updated_at: String
+
+      attr_accessor updated_by: String
+
+      attr_accessor archived_at: String?
+
+      attr_accessor archived_by: String?
+
+      attr_accessor schedule: Courier::BroadcastSchedule?
+
+      def initialize: (
+        id: String,
+        channel: Courier::Models::Broadcast::channel,
+        created_at: String,
+        created_by: String,
+        name: String,
+        status: Courier::Models::Broadcast::status,
+        updated_at: String,
+        updated_by: String,
+        ?archived_at: String?,
+        ?archived_by: String?,
+        ?schedule: Courier::BroadcastSchedule?
+      ) -> void
+
+      def to_hash: -> {
+        id: String,
+        channel: Courier::Models::Broadcast::channel,
+        created_at: String,
+        created_by: String,
+        name: String,
+        status: Courier::Models::Broadcast::status,
+        updated_at: String,
+        updated_by: String,
+        archived_at: String?,
+        archived_by: String?,
+        schedule: Courier::BroadcastSchedule?
+      }
+
+      type channel = :email | :sms | :push | :inbox | :slack | :msteams
+
+      module Channel
+        extend Courier::Internal::Type::Enum
+
+        EMAIL: :email
+        SMS: :sms
+        PUSH: :push
+        INBOX: :inbox
+        SLACK: :slack
+        MSTEAMS: :msteams
+
+        def self?.values: -> ::Array[Courier::Models::Broadcast::channel]
+      end
+
+      type status = :draft | :scheduled | :sending | :sent
+
+      module Status
+        extend Courier::Internal::Type::Enum
+
+        DRAFT: :draft
+        SCHEDULED: :scheduled
+        SENDING: :sending
+        SENT: :sent
+
+        def self?.values: -> ::Array[Courier::Models::Broadcast::status]
+      end
+    end
+  end
+end

data/sig/courier/models/broadcast_archive_params.rbs

@@ -0,0 +1,23 @@
+module Courier
+  module Models
+    type broadcast_archive_params =
+      { broadcast_id: String } & Courier::Internal::Type::request_parameters
+
+    class BroadcastArchiveParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor broadcast_id: String
+
+      def initialize: (
+        broadcast_id: String,
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        broadcast_id: String,
+        request_options: Courier::RequestOptions
+      }
+    end
+  end
+end

data/sig/courier/models/broadcast_cancel_params.rbs

@@ -0,0 +1,23 @@
+module Courier
+  module Models
+    type broadcast_cancel_params =
+      { broadcast_id: String } & Courier::Internal::Type::request_parameters
+
+    class BroadcastCancelParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor broadcast_id: String
+
+      def initialize: (
+        broadcast_id: String,
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        broadcast_id: String,
+        request_options: Courier::RequestOptions
+      }
+    end
+  end
+end

data/sig/courier/models/broadcast_create_params.rbs

@@ -0,0 +1,15 @@
+module Courier
+  module Models
+    type broadcast_create_params =
+      {  } & Courier::Internal::Type::request_parameters
+
+    class BroadcastCreateParams < Courier::Models::CreateBroadcastRequest
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      def initialize: (?request_options: Courier::request_opts) -> void
+
+      def to_hash: -> { request_options: Courier::RequestOptions }
+    end
+  end
+end

data/sig/courier/models/broadcast_duplicate_params.rbs

@@ -0,0 +1,23 @@
+module Courier
+  module Models
+    type broadcast_duplicate_params =
+      { broadcast_id: String } & Courier::Internal::Type::request_parameters
+
+    class BroadcastDuplicateParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor broadcast_id: String
+
+      def initialize: (
+        broadcast_id: String,
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        broadcast_id: String,
+        request_options: Courier::RequestOptions
+      }
+    end
+  end
+end

data/sig/courier/models/broadcast_list_params.rbs

@@ -0,0 +1,30 @@
+module Courier
+  module Models
+    type broadcast_list_params =
+      { cursor: String?, limit: Integer }
+      & Courier::Internal::Type::request_parameters
+
+    class BroadcastListParams < Courier::Internal::Type::BaseModel
+      extend Courier::Internal::Type::RequestParameters::Converter
+      include Courier::Internal::Type::RequestParameters
+
+      attr_accessor cursor: String?
+
+      attr_reader limit: Integer?
+
+      def limit=: (Integer) -> Integer
+
+      def initialize: (
+        ?cursor: String?,
+        ?limit: Integer,
+        ?request_options: Courier::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        cursor: String?,
+        limit: Integer,
+        request_options: Courier::RequestOptions
+      }
+    end
+  end
+end