trycourier 4.20.0 → 4.22.0

data/rbi/courier/resources/profiles/lists.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Profiles
+      # Store the contact information Courier delivers to for each user — email, phone
+      # number, push tokens, and any custom data you send to.
       class Lists
-        # Returns the subscribed lists for a specified user.
+        # Returns the lists a user is subscribed to, with paging. Use it to check what a
+        # recipient will receive before sending to a list.
         sig do
           params(
             user_id: String,
@@ -22,7 +25,8 @@ module Courier
         )
         end
 
-        # Removes all list subscriptions for given user.
+        # Removes every list subscription for a user at once. Their profile and
+        # preferences are untouched, so this only affects list-targeted sends.
         sig do
           params(
             user_id: String,
@@ -36,20 +40,35 @@ module Courier
         )
         end
 
-        # Subscribes the given user to one or more lists. If the list does not exist, it
-        # will be created.
+        # Subscribes a user to one or more lists, creating any list that does not yet
+        # exist. Optional preferences apply to each subscription.
         sig do
           params(
             user_id: String,
             lists: T::Array[Courier::SubscribeToListsRequestItem::OrHash],
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::Models::Profiles::ListSubscribeResponse)
         end
         def subscribe(
-          # A unique identifier representing the user associated with the requested user
-          # profile.
+          # Path param: A unique identifier representing the user associated with the
+          # requested user profile.
           user_id,
+          # Body param
           lists:,
+          # 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/profiles.rbi

@@ -2,28 +2,49 @@
 
 module Courier
   module Resources
+    # Store the contact information Courier delivers to for each user — email, phone
+    # number, push tokens, and any custom data you send to.
     class Profiles
+      # Store the contact information Courier delivers to for each user — email, phone
+      # number, push tokens, and any custom data you send to.
       sig { returns(Courier::Resources::Profiles::Lists) }
       attr_reader :lists
 
-      # Merge the supplied values with an existing profile or create a new profile if
-      # one doesn't already exist.
+      # Merges the supplied values into a user's profile, creating it if absent and
+      # leaving any key you omit untouched. Prefer this for everyday writes.
       sig do
         params(
           user_id: String,
           profile: T::Hash[Symbol, T.anything],
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Models::ProfileCreateResponse)
       end
       def create(
-        # A unique identifier representing the user associated with the requested profile.
+        # Path param: A unique identifier representing the user associated with the
+        # requested profile.
         user_id,
+        # Body param
         profile:,
+        # 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
 
-      # Returns the specified user profile.
+      # Returns a user's stored profile and preferences, including the email address,
+      # phone number, and push tokens Courier can reach them on.
       sig do
         params(
           user_id: String,
@@ -37,7 +58,8 @@ module Courier
       )
       end
 
-      # Update a profile
+      # Applies a JSON Patch to a user profile, adding, removing, or replacing
+      # individual fields without sending the whole object.
       sig do
         params(
           user_id: String,
@@ -55,7 +77,8 @@ module Courier
       )
       end
 
-      # Deletes the specified user profile.
+      # Deletes a user's profile and stored contact details. List subscriptions and
+      # preferences are separate resources, so remove those too if required.
       sig do
         params(
           user_id: String,
@@ -70,11 +93,8 @@ module Courier
       )
       end
 
-      # When using `PUT`, be sure to include all the key-value pairs required by the
-      # recipient's profile. Any key-value pairs that exist in the profile but fail to
-      # be included in the `PUT` request will be removed from the profile. Remember, a
-      # `PUT` update is a full replacement of the data. For partial updates, use the
-      # [Patch](https://www.courier.com/docs/reference/profiles/patch/) request.
+      # Overwrites a user profile in full, removing any key absent from the request
+      # body. Use the patch endpoint when changing a single field.
       sig do
         params(
           user_id: String,

data/rbi/courier/resources/providers/catalog.rbi

@@ -3,11 +3,11 @@
 module Courier
   module Resources
     class Providers
+      # Configure the channel providers Courier delivers through, and browse the
+      # provider types it supports.
       class Catalog
-        # Returns the catalog of available provider types with their display names,
-        # descriptions, and configuration schema fields (snake_case, with `type` and
-        # `required`). Providers with no configurable schema return only `provider`,
-        # `name`, and `description`.
+        # Returns the provider types Courier supports, each with a display name,
+        # description, and the configuration fields it requires.
         sig do
           params(
             channel: String,

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,