trycourier 4.21.0 → 4.23.0

data/rbi/courier/resources/providers.rbi

@@ -2,38 +2,57 @@
 
 module Courier
   module Resources
+    # Configure the channel providers Courier delivers through, and browse the
+    # provider types it supports.
     class Providers
+      # Configure the channel providers Courier delivers through, and browse the
+      # provider types it supports.
       sig { returns(Courier::Resources::Providers::Catalog) }
       attr_reader :catalog
 
-      # Create a new provider configuration. The `provider` field must be a known
-      # Courier provider key (see catalog).
+      # Configures a provider integration from a Courier provider key and its settings.
+      # Check the catalog endpoint for the schema each provider expects.
       sig do
         params(
           provider: String,
           alias_: String,
           settings: T::Hash[Symbol, T.anything],
           title: String,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Provider)
       end
       def create(
-        # The provider key identifying the type (e.g. "sendgrid", "twilio"). Must be a
-        # known Courier provider — see the catalog endpoint for valid keys.
+        # Body param: The provider key identifying the type (e.g. "sendgrid", "twilio").
+        # Must be a known Courier provider — see the catalog endpoint for valid keys.
         provider:,
-        # Optional alias for this configuration.
+        # Body param: Optional alias for this configuration.
         alias_: nil,
-        # Provider-specific settings (snake_case keys). Defaults to an empty object when
-        # omitted. Use the catalog endpoint to discover required fields for a given
-        # provider — omitting a required field returns a 400 validation error.
+        # Body param: Provider-specific settings (snake_case keys). Defaults to an empty
+        # object when omitted. Use the catalog endpoint to discover required fields for a
+        # given provider — omitting a required field returns a 400 validation error.
         settings: nil,
-        # Optional display title. Omit to use "Default Configuration".
+        # Body param: Optional display title. Omit to use "Default Configuration".
         title: 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
 
-      # Fetch a single provider configuration by ID.
+      # Returns one configured provider by id, including its channel, provider key,
+      # alias, title, and current settings.
       sig do
         params(
           id: String,
@@ -47,11 +66,8 @@ module Courier
       )
       end
 
-      # Replace an existing provider configuration. The `provider` key is required and
-      # determines which provider-specific settings schema is applied. All other fields
-      # are optional — omitted fields are cleared from the stored configuration (this is
-      # a full replacement, not a partial merge). Changing the provider type for an
-      # existing configuration is not supported.
+      # Replaces a provider's configuration in full, clearing any field you omit rather
+      # than merging it. Send the complete settings object.
       sig do
         params(
           id: String,
@@ -80,8 +96,8 @@ module Courier
       )
       end
 
-      # List configured provider integrations for the current workspace. Supports
-      # cursor-based pagination.
+      # Lists the provider integrations configured in the workspace, one entry per
+      # channel and provider key with its alias and settings.
       sig do
         params(
           cursor: String,
@@ -95,8 +111,8 @@ module Courier
       )
       end
 
-      # Delete a provider configuration. Returns 409 if the provider is still referenced
-      # by routing or notifications.
+      # Deletes a provider configuration, which fails while routing strategies or
+      # templates still reference it. Update those references first.
       sig do
         params(
           id: String,

data/rbi/courier/resources/requests.rbi

@@ -2,8 +2,11 @@
 
 module Courier
   module Resources
+    # Look up the messages Courier has accepted, inspect their delivery history and
+    # rendered output, and cancel, resend, or archive them.
     class Requests
-      # Archive message
+      # Archives a send request by its request id. Use it to remove test sends or
+      # superseded requests from the message list without deleting them.
       sig do
         params(
           request_id: String,

data/rbi/courier/resources/routing_strategies.rbi

@@ -2,6 +2,8 @@
 
 module Courier
   module Resources
+    # Define reusable channel routing and failover strategies, and see which templates
+    # use them.
     class RoutingStrategies
       # Create a routing strategy. Requires a name and routing configuration at minimum.
       # Channels and providers default to empty if omitted.
@@ -14,28 +16,42 @@ module Courier
           providers:
             T.nilable(T::Hash[Symbol, Courier::MessageProvidersType::OrHash]),
           tags: T.nilable(T::Array[String]),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::RoutingStrategyGetResponse)
       end
       def create(
-        # Human-readable name for the routing strategy.
+        # Body param: Human-readable name for the routing strategy.
         name:,
-        # Routing tree defining channel selection method and order.
+        # Body param: Routing tree defining channel selection method and order.
         routing:,
-        # Per-channel delivery configuration. Defaults to empty if omitted.
+        # Body param: Per-channel delivery configuration. Defaults to empty if omitted.
         channels: nil,
-        # Optional description of the routing strategy.
+        # Body param: Optional description of the routing strategy.
         description: nil,
-        # Per-provider delivery configuration. Defaults to empty if omitted.
+        # Body param: Per-provider delivery configuration. Defaults to empty if omitted.
         providers: nil,
-        # Optional tags for categorization.
+        # Body param: Optional tags for categorization.
         tags: 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 routing strategy by ID. Returns the full entity including routing
-      # content and metadata.
+      # Returns one routing strategy by id with its name, tags, channels, and the
+      # routing rules that decide provider order and fallback.
       sig do
         params(
           id: String,
@@ -83,8 +99,8 @@ module Courier
       )
       end
 
-      # List notification templates associated with a routing strategy. Includes
-      # template metadata only, not full content.
+      # Returns the notification templates using a routing strategy, with paging. Check
+      # this before changing a strategy that templates depend on.
       sig do
         params(
           id: String,

data/rbi/courier/resources/send.rbi

@@ -2,18 +2,35 @@
 
 module Courier
   module Resources
+    # Send a message to one or more recipients — users, lists, audiences, or tenants —
+    # across every channel you have configured.
     class Send
-      # Send a message to one or more recipients.
+      # Sends a message to one or more recipients and returns a requestId. Courier
+      # routes it to email, SMS, push, chat, or in-app based on your rules.
       sig do
         params(
           message: Courier::SendMessageParams::Message::OrHash,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Models::SendMessageResponse)
       end
       def message(
-        # The message property has the following primary top-level properties. They define
-        # the destination and content of the message.
+        # Body param: The message property has the following primary top-level properties.
+        # They define the destination and content of the message.
         message:,
+        # 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/rbi/courier/resources/tenants/preferences/items.rbi

@@ -4,8 +4,11 @@ module Courier
   module Resources
     class Tenants
       class Preferences
+        # Manage tenants — the organizations, teams, or accounts your users belong to —
+        # along with their users and default preferences.
         class Items
-          # Create or Replace Default Preferences For Topic
+          # Sets a tenant's default opt-in status for one subscription topic, which applies
+          # to every member unless a user sets their own override.
           sig do
             params(
               topic_id: String,
@@ -36,7 +39,8 @@ module Courier
           )
           end
 
-          # Remove Default Preferences For Topic
+          # Removes a tenant's default preference for one subscription topic, addressed by
+          # tenant id and topic id.
           sig do
             params(
               topic_id: String,

data/rbi/courier/resources/tenants/preferences.rbi

@@ -4,6 +4,8 @@ module Courier
   module Resources
     class Tenants
       class Preferences
+        # Manage tenants — the organizations, teams, or accounts your users belong to —
+        # along with their users and default preferences.
         sig { returns(Courier::Resources::Tenants::Preferences::Items) }
         attr_reader :items
 

data/rbi/courier/resources/tenants/templates/versions.rbi

@@ -4,14 +4,11 @@ module Courier
   module Resources
     class Tenants
       class Templates
+        # Manage the templates and template versions scoped to a single tenant, including
+        # the ones authored in the embedded designer.
         class Versions
-          # Fetches a specific version of a tenant template.
-          #
-          # Supports the following version formats:
-          #
-          # - `latest` - The most recent version of the template
-          # - `published` - The currently published version
-          # - `v{version}` - A specific version (e.g., "v1", "v2", "v1.0.0")
+          # Returns one version of a tenant template, addressed by version number or by
+          # latest, with its content and publish timestamp.
           sig do
             params(
               version: String,

data/rbi/courier/resources/tenants/templates.rbi

@@ -3,11 +3,16 @@
 module Courier
   module Resources
     class Tenants
+      # Manage the templates and template versions scoped to a single tenant, including
+      # the ones authored in the embedded designer.
       class Templates
+        # Manage the templates and template versions scoped to a single tenant, including
+        # the ones authored in the embedded designer.
         sig { returns(Courier::Resources::Tenants::Templates::Versions) }
         attr_reader :versions
 
-        # Get a Template in Tenant
+        # Returns a tenant's notification template with its content, version, and created,
+        # updated, and published timestamps.
         sig do
           params(
             template_id: String,
@@ -24,7 +29,8 @@ module Courier
         )
         end
 
-        # List Templates in Tenant
+        # Lists a tenant's notification templates, each carrying its version and published
+        # timestamp. Paged.
         sig do
           params(
             tenant_id: String,
@@ -44,12 +50,8 @@ module Courier
         )
         end
 
-        # Deletes the tenant's notification template with the given `template_id`.
-        #
-        # Returns **204 No Content** with an empty body on success.
-        #
-        # Returns **404** if there is no template with this ID for the tenant, including a
-        # second `DELETE` after a successful removal.
+        # Deletes a tenant's notification template by id. Sends for that tenant then use
+        # the workspace template registered under the same id.
         sig do
           params(
             template_id: String,
@@ -66,10 +68,8 @@ module Courier
         )
         end
 
-        # Publishes a specific version of a notification template for a tenant.
-        #
-        # The template must already exist in the tenant's notification map. If no version
-        # is specified, defaults to publishing the "latest" version.
+        # Publishes a version of a tenant's notification template, making it the content
+        # that tenant's sends render from until you publish another.
         sig do
           params(
             template_id: String,
@@ -90,13 +90,8 @@ module Courier
         )
         end
 
-        # Creates or updates a notification template for a tenant.
-        #
-        # If the template already exists for the tenant, it will be updated (200).
-        # Otherwise, a new template is created (201).
-        #
-        # Optionally publishes the template immediately if the `published` flag is set to
-        # true.
+        # Creates or updates a notification template scoped to one tenant, letting a
+        # tenant override the content the workspace template would send.
         sig do
           params(
             template_id: String,

data/rbi/courier/resources/tenants.rbi

@@ -2,14 +2,19 @@
 
 module Courier
   module Resources
+    # Manage tenants — the organizations, teams, or accounts your users belong to —
+    # along with their users and default preferences.
     class Tenants
       sig { returns(Courier::Resources::Tenants::Preferences) }
       attr_reader :preferences
 
+      # Manage the templates and template versions scoped to a single tenant, including
+      # the ones authored in the embedded designer.
       sig { returns(Courier::Resources::Tenants::Templates) }
       attr_reader :templates
 
-      # Get a Tenant
+      # Returns one tenant with its name, parent tenant id, default preferences,
+      # properties, and the user profile applied to its members.
       sig do
         params(
           tenant_id: String,
@@ -23,7 +28,8 @@ module Courier
       )
       end
 
-      # Create or Replace a Tenant
+      # Creates or replaces a tenant from a name, parent, brand, properties, and default
+      # preferences supplied in the request body.
       sig do
         params(
           tenant_id: String,
@@ -56,7 +62,8 @@ module Courier
       )
       end
 
-      # Get a List of Tenants
+      # Lists the workspace's tenants, each carrying a name, parent tenant, properties,
+      # and default preferences. Paged.
       sig do
         params(
           cursor: T.nilable(String),
@@ -76,7 +83,8 @@ module Courier
       )
       end
 
-      # Delete a Tenant
+      # Deletes a tenant. Its members' workspace-level profiles and preferences live
+      # outside the tenant and are managed separately.
       sig do
         params(
           tenant_id: String,
@@ -90,7 +98,8 @@ module Courier
       )
       end
 
-      # Get Users in Tenant
+      # Returns the users belonging to a tenant with cursor paging. Use it to see who a
+      # tenant-scoped send will reach.
       sig do
         params(
           tenant_id: String,

data/rbi/courier/resources/translations.rbi

@@ -2,8 +2,11 @@
 
 module Courier
   module Resources
+    # Store and retrieve the translation strings Courier uses to render localized
+    # template content.
     class Translations
-      # Get translations by locale
+      # Returns the translation strings stored for one domain and locale, for use in
+      # localized notification content.
       sig do
         params(
           locale: String,
@@ -21,7 +24,8 @@ module Courier
       )
       end
 
-      # Update a translation
+      # Uploads the translation strings for one domain and locale. Courier uses them to
+      # render localized content for recipients in that locale.
       sig do
         params(
           locale: String,

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,