trycourier 4.21.0 → 4.22.0

data/rbi/courier/resources/users/preferences.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Users
+      # Read and write a single user's notification preferences, per topic and per
+      # channel.
       class Preferences
-        # Fetch all user preferences.
+        # Returns a user's preference overrides with paging, one entry per subscription
+        # topic they have set a choice for.
         sig do
           params(
             user_id: String,
@@ -22,23 +25,8 @@ module Courier
         )
         end
 
-        # Replace a user's complete set of preference overrides in a single request. The
-        # topics in the request body become the recipient's entire set of overrides:
-        # listed topics are created or updated, and every existing override that is not
-        # included in the body is reset to its topic default. Submitting an empty `topics`
-        # array is a valid clear-all that resets every existing override.
-        #
-        # This operation is validation-atomic (all-or-nothing): structural validation
-        # fails fast with a single `400`, and if any topic is semantically invalid (an
-        # unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing
-        # request that is not available on the workspace's plan) the request returns a
-        # single `400` aggregating every failure in `errors` and writes nothing. On
-        # success it returns `200` with `items` (the complete resulting override set) and
-        # `deleted` (the ids of the overrides that were reset to default).
-        #
-        # Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is
-        # returned in Courier's canonical topic id form, regardless of the form supplied
-        # in the request.
+        # Replaces a user's entire set of preference overrides. Any topic you leave out is
+        # reset to its default, so send the full set rather than a subset.
         sig do
           params(
             user_id: String,
@@ -64,23 +52,8 @@ module Courier
         )
         end
 
-        # Additively create or update a user's preferences for one or more subscription
-        # topics in a single request. Only the topics included in the request body are
-        # created or updated; any existing overrides for topics not listed are left
-        # untouched.
-        #
-        # Structural validation of the request body fails fast with a single `400`. Beyond
-        # that, each topic is processed independently (partial-success, not
-        # all-or-nothing): valid topics are written and returned in `items`, while topics
-        # that cannot be applied are collected in `errors` with a per-topic `reason` (for
-        # example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom
-        # routing request that is not available on the workspace's plan, or a write
-        # failure). The request therefore returns `200` with both lists whenever the body
-        # is structurally valid.
-        #
-        # Every `topic_id` in the response — in both `items` and `errors` — is returned in
-        # Courier's canonical topic id form, regardless of the form supplied in the
-        # request.
+        # Adds or updates a user's preferences for several subscription topics at once.
+        # Topics you leave out keep whatever they were set to before.
         sig do
           params(
             user_id: String,
@@ -89,6 +62,8 @@ module Courier
                 Courier::Users::PreferenceBulkUpdateParams::Topic::OrHash
               ],
             tenant_id: T.nilable(String),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::Models::Users::PreferenceBulkUpdateResponse)
         end
@@ -101,13 +76,24 @@ module Courier
           topics:,
           # Query param: Update the preferences of a user for this specific tenant context.
           tenant_id: 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
 
-        # Remove a user's preferences for a specific subscription topic, resetting the
-        # topic to its effective default. This operation is idempotent: deleting a
-        # preference that does not exist succeeds with no error.
+        # Removes a user's override for one subscription topic, resetting it to the
+        # effective default from the tenant or workspace.
         sig do
           params(
             topic_id: String,
@@ -128,7 +114,8 @@ module Courier
         )
         end
 
-        # Fetch user preferences for a specific subscription topic.
+        # Returns a user's opt-in status and channel choices for one subscription topic,
+        # or the effective default if they have set no override.
         sig do
           params(
             topic_id: String,
@@ -149,7 +136,8 @@ module Courier
         )
         end
 
-        # Update or Create user preferences for a specific subscription topic.
+        # Sets a user's opt-in status and channel choices for one subscription topic,
+        # overriding the tenant default for that topic only.
         sig do
           params(
             topic_id: String,

data/rbi/courier/resources/users/tenants.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Users
+      # Associate a user with one or more tenants, and read or remove those
+      # associations.
       class Tenants
-        # Returns a paginated list of user tenant associations.
+        # Returns the tenants a user belongs to, with cursor paging. A user can belong to
+        # many tenants, each with its own profile and preferences.
         sig do
           params(
             user_id: String,
@@ -24,9 +27,8 @@ module Courier
         )
         end
 
-        # This endpoint is used to add a user to multiple tenants in one call. A custom
-        # profile can also be supplied for each tenant. This profile will be merged with
-        # the user's main profile when sending to the user with that tenant.
+        # Adds a user to several tenants in one call, each optionally with a per-tenant
+        # profile that overrides their workspace profile.
         sig do
           params(
             user_id: String,
@@ -42,10 +44,8 @@ module Courier
         )
         end
 
-        # This endpoint is used to add a single tenant.
-        #
-        # A custom profile can also be supplied with the tenant. This profile will be
-        # merged with the user's main profile when sending to the user with that tenant.
+        # Adds a user to one tenant, optionally with a tenant-specific profile that
+        # overrides their workspace profile for sends in that tenant.
         sig do
           params(
             tenant_id: String,
@@ -65,7 +65,8 @@ module Courier
         )
         end
 
-        # Removes a user from any tenants they may have been associated with.
+        # Removes a user from every tenant they belong to in one call. Their
+        # workspace-level profile is a separate resource.
         sig do
           params(
             user_id: String,
@@ -79,7 +80,8 @@ module Courier
         )
         end
 
-        # Removes a user from the supplied tenant.
+        # Removes a user from one tenant. Their other tenant memberships and workspace
+        # profile are managed through separate endpoints.
         sig do
           params(
             tenant_id: String,

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

@@ -32,6 +32,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/inbox/message_delete_params.rbs

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