trycourier 4.21.0 → 4.23.0

data/rbi/courier/resources/lists/subscriptions.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Lists
+      # Manage static groups of users that you subscribe explicitly, and send to them by
+      # list id or list pattern.
       class Subscriptions
-        # Get the list's subscriptions.
+        # Returns the users subscribed to a list with paging, each with the preferences
+        # recorded for that subscription.
         sig do
           params(
             list_id: String,
@@ -27,13 +30,28 @@ module Courier
           params(
             list_id: String,
             recipients: T::Array[Courier::PutSubscriptionsRecipient::OrHash],
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).void
         end
         def add(
-          # A unique identifier representing the list you wish to retrieve.
+          # Path param: A unique identifier representing the list you wish to retrieve.
           list_id,
+          # Body param
           recipients:,
+          # 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
@@ -55,8 +73,8 @@ module Courier
         )
         end
 
-        # Subscribe a user to an existing list (note: if the List does not exist, it will
-        # be automatically created).
+        # Subscribes one user to a list, creating the list if it does not yet exist.
+        # Optional preferences apply to this subscription only.
         sig do
           params(
             user_id: String,
@@ -77,7 +95,8 @@ module Courier
         )
         end
 
-        # Delete a subscription to a list by list ID and user ID.
+        # Removes one user's subscription to a list, addressed by list id and user id. The
+        # user's profile and other subscriptions are separate resources.
         sig do
           params(
             user_id: String,

data/rbi/courier/resources/lists.rbi

@@ -2,11 +2,16 @@
 
 module Courier
   module Resources
+    # Manage static groups of users that you subscribe explicitly, and send to them by
+    # list id or list pattern.
     class Lists
+      # Manage static groups of users that you subscribe explicitly, and send to them by
+      # list id or list pattern.
       sig { returns(Courier::Resources::Lists::Subscriptions) }
       attr_reader :subscriptions
 
-      # Returns a list based on the list ID provided.
+      # Returns one list by id with its name and created and updated timestamps. Fetch
+      # its subscribers separately with the subscriptions endpoint.
       sig do
         params(
           list_id: String,
@@ -20,7 +25,8 @@ module Courier
       )
       end
 
-      # Create or replace an existing list with the supplied values.
+      # Creates or replaces a list from a name and preferences. Subscribers are managed
+      # through the separate subscriptions endpoints.
       sig do
         params(
           list_id: String,
@@ -38,7 +44,8 @@ module Courier
       )
       end
 
-      # Returns all of the lists, with the ability to filter based on a pattern.
+      # Returns the workspace's lists, filterable by a pattern to fetch a subset such as
+      # every regional list. Paged by cursor.
       sig do
         params(
           cursor: T.nilable(String),
@@ -58,7 +65,8 @@ module Courier
       )
       end
 
-      # Delete a list by list ID.
+      # Deletes a list, halting sends that target it. A previously deleted list can be
+      # brought back with the companion restore endpoint.
       sig do
         params(
           list_id: String,
@@ -72,7 +80,8 @@ module Courier
       )
       end
 
-      # Restore a previously deleted list.
+      # Restores a previously deleted list along with its subscribers, so a list removed
+      # by mistake can be brought back rather than rebuilt.
       sig do
         params(
           list_id: String,

data/rbi/courier/resources/messages.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 Messages
-      # Fetch the status of a message you've previously sent.
+      # Returns a sent message's status, recipient, event, and per-provider delivery
+      # detail, with timestamps for enqueued, sent, delivered, opened, and clicked.
       sig do
         params(
           message_id: String,
@@ -18,7 +21,8 @@ module Courier
       )
       end
 
-      # Fetch the statuses of messages you've previously sent.
+      # Returns previously sent messages, most recent first, each carrying its status,
+      # recipient, channel, and provider. Paged by cursor.
       sig do
         params(
           archived: T.nilable(T::Boolean),
@@ -80,11 +84,8 @@ module Courier
       )
       end
 
-      # Cancel a message that is currently in the process of being delivered. A
-      # well-formatted API call to the cancel message API will return either `200`
-      # status code for a successful cancellation or `409` status code for an
-      # unsuccessful cancellation. Both cases will include the actual message record in
-      # the response body (see details below).
+      # Cancels a message that is still in the delivery pipeline and returns the message
+      # record with its resulting canceled or failed status.
       sig do
         params(
           message_id: String,
@@ -98,7 +99,8 @@ module Courier
       )
       end
 
-      # Get message content
+      # Returns the rendered content Courier delivered for a message, broken out per
+      # channel, to confirm what the recipient received.
       sig do
         params(
           message_id: String,
@@ -113,7 +115,8 @@ module Courier
       )
       end
 
-      # Fetch the array of events of a message you've previously sent.
+      # Returns the ordered event history for a sent message, one entry per status
+      # transition with its timestamp.
       sig do
         params(
           message_id: String,
@@ -130,11 +133,8 @@ module Courier
       )
       end
 
-      # Resend a previously sent message. The original send request is loaded from
-      # storage and a brand-new send is enqueued for the same recipient and content,
-      # producing a **new** `messageId` — the original message is not modified.
-      # Throttled by a per-message rate limit; a repeat inside the limit window returns
-      # `429 Too Many Requests`.
+      # Resends a previously sent message to the same recipient and content, returning a
+      # new messageId. The original send request is not modified.
       sig do
         params(
           message_id: String,

data/rbi/courier/resources/notifications/checks.rbi

@@ -3,8 +3,11 @@
 module Courier
   module Resources
     class Notifications
+      # Create, update, version, publish, and localize notification templates and their
+      # content.
       class Checks
-        # Replace the submission checks for a notification template.
+        # Replaces the approval checks on a template submission with the complete set
+        # supplied in the request body.
         sig do
           params(
             submission_id: String,
@@ -24,7 +27,8 @@ module Courier
         )
         end
 
-        # Retrieve the submission checks for a notification template.
+        # Returns the approval checks recorded for a template submission, each with its
+        # pass or fail result.
         sig do
           params(
             submission_id: String,
@@ -41,7 +45,8 @@ module Courier
         )
         end
 
-        # Cancel a submission for a notification template.
+        # Cancels a pending template submission, withdrawing it from the approval
+        # workflow. The template stays in draft and can be resubmitted later.
         sig do
           params(
             submission_id: String,

data/rbi/courier/resources/notifications.rbi

@@ -2,7 +2,11 @@
 
 module Courier
   module Resources
+    # Create, update, version, publish, and localize notification templates and their
+    # content.
     class Notifications
+      # Create, update, version, publish, and localize notification templates and their
+      # content.
       sig { returns(Courier::Resources::Notifications::Checks) }
       attr_reader :checks
 
@@ -12,16 +16,30 @@ module Courier
         params(
           notification: Courier::NotificationTemplatePayload::OrHash,
           state: Courier::NotificationTemplateCreateRequest::State::OrSymbol,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::NotificationTemplateResponse)
       end
       def create(
-        # Core template fields used in POST and PUT request bodies (nested under a
-        # `notification` key) and returned at the top level in responses.
+        # Body param: Core template fields used in POST and PUT request bodies (nested
+        # under a `notification` key) and returned at the top level in responses.
         notification:,
-        # Template state after creation. Case-insensitive input, normalized to uppercase
-        # in the response. Defaults to "DRAFT".
+        # Body param: Template state after creation. Case-insensitive input, normalized to
+        # uppercase in the response. Defaults to "DRAFT".
         state: 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
@@ -45,7 +63,8 @@ module Courier
       )
       end
 
-      # List notification templates in your workspace.
+      # Lists the workspace's notification templates. Each carries a name, tags, brand,
+      # routing, and its draft or published state.
       sig do
         params(
           cursor: T.nilable(String),
@@ -65,7 +84,8 @@ module Courier
       )
       end
 
-      # Archive a notification template.
+      # Archives a notification template, preventing new sends from referencing it. The
+      # template stays retrievable for its version history.
       sig do
         params(
           id: String,
@@ -79,12 +99,9 @@ module Courier
       )
       end
 
-      # Duplicate a notification template. Creates a standalone copy within the same
-      # workspace and environment, with " COPY" appended to the title. The copy clones
-      # the source draft's tags, brand, subscription topic, routing strategy, channels,
-      # and content, and is always created as a standalone template (it is not linked to
-      # any journey or broadcast, even if the source was). Templates that are scoped to
-      # a journey or a broadcast cannot be duplicated through this endpoint.
+      # Copies a notification template within the same workspace and environment,
+      # appending " COPY" to the title. The copy is standalone and independently
+      # editable.
       sig do
         params(
           id: String,
@@ -98,7 +115,8 @@ module Courier
       )
       end
 
-      # List versions of a notification template.
+      # Returns a notification template's published versions, most recent first, for
+      # comparison or rollback. Paged.
       sig do
         params(
           id: String,
@@ -124,21 +142,35 @@ module Courier
         params(
           id: String,
           version: String,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).void
       end
       def publish(
-        # Template ID (nt\_ prefix).
+        # Path param: Template ID (nt\_ prefix).
         id,
-        # Historical version to publish (e.g. "v001"). Omit to publish the current draft.
+        # Body param: Historical version to publish (e.g. "v001"). Omit to publish the
+        # current draft.
         version: 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
 
-      # Replace the elemental content of a notification template. Overwrites all
-      # elements in the template with the provided content. Only supported for V2
-      # (elemental) templates.
+      # Replaces all Elemental content in a template, overwriting every existing
+      # element. Supported for V2 templates only, not V1 blocks and channels.
       sig do
         params(
           id: String,
@@ -158,8 +190,8 @@ module Courier
       )
       end
 
-      # Update a single element within a notification template. Only supported for V2
-      # (elemental) templates.
+      # Replaces one Elemental element in a template, addressed by its element id.
+      # Supported for V2 templates only, not V1 blocks and channels.
       sig do
         params(
           element_id: String,
@@ -197,9 +229,8 @@ module Courier
       )
       end
 
-      # Set locale-specific content overrides for a notification template. Each element
-      # override must reference an existing element by ID. Only supported for V2
-      # (elemental) templates.
+      # Sets locale-specific content overrides for a template. Each override must
+      # reference an element that already exists in the default content.
       sig do
         params(
           locale_id: String,
@@ -223,7 +254,8 @@ module Courier
       )
       end
 
-      # Replace a notification template. All fields are required.
+      # Replaces a notification template in full, so send every field rather than only
+      # the ones you want changed. Publish separately to make it live.
       sig do
         params(
           id: String,
@@ -245,10 +277,8 @@ module Courier
       )
       end
 
-      # Retrieve the content of a notification template. The response shape depends on
-      # whether the template uses V1 (blocks/channels) or V2 (elemental) content. Use
-      # the `version` query parameter to select draft, published, or a specific
-      # historical version.
+      # Returns a template's content and checksum. V2 templates return Elemental
+      # elements, while V1 templates return blocks and channels instead.
       sig do
         params(
           id: String,

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,