trycourier 4.21.0 → 4.22.0

data/rbi/courier/resources/journeys.rbi

@@ -2,16 +2,16 @@
 
 module Courier
   module Resources
+    # Build, version, publish, invoke, and cancel multi-step notification workflows,
+    # along with the templates scoped to them.
     class Journeys
+      # Build, version, publish, invoke, and cancel multi-step notification workflows,
+      # along with the templates scoped to them.
       sig { returns(Courier::Resources::Journeys::Templates) }
       attr_reader :templates
 
-      # Create a journey. Defaults to `DRAFT` state; pass `state: "PUBLISHED"` to
-      # publish on create. Send nodes are not allowed on `POST`. The standard flow is:
-      # create the journey shell here, add notification templates with
-      # `POST /journeys/{templateId}/templates`, then wire them into the journey with
-      # `PUT /journeys/{templateId}`. Call `POST /journeys/{templateId}/publish` to
-      # publish a draft after the fact.
+      # Creates a journey from a set of nodes, in draft state unless you pass a
+      # published state. Send nodes cannot be included until their templates exist.
       sig do
         params(
           name: String,
@@ -36,15 +36,32 @@ module Courier
             ],
           enabled: T::Boolean,
           state: Courier::JourneyState::OrSymbol,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::JourneyResponse)
       end
       def create(
+        # Body param
         name:,
+        # Body param
         nodes:,
+        # Body param
         enabled: nil,
-        # Lifecycle state of a journey.
+        # Body param: Lifecycle state of a journey.
         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
@@ -67,7 +84,8 @@ module Courier
       )
       end
 
-      # Get the list of journeys.
+      # Lists the workspace's journeys, each carrying a name, state, and enabled flag.
+      # Paged by cursor.
       sig do
         params(
           cursor: String,
@@ -86,8 +104,8 @@ module Courier
       )
       end
 
-      # Archive a journey. Archived journeys cannot be invoked. Existing journey runs
-      # continue to completion.
+      # Archives a journey so it can no longer be invoked. Runs already in flight
+      # continue to completion, so archiving never strands a user mid-sequence.
       sig do
         params(
           template_id: String,
@@ -101,12 +119,8 @@ module Courier
       )
       end
 
-      # Cancel journey runs. The request body must include EXACTLY ONE of
-      # `cancelation_token` (cancels every run associated with the token) or `run_id`
-      # (cancels a single tenant-scoped run). Supplying both or neither returns a `400`.
-      # A `run_id` that does not match a run for the tenant returns `404`. Cancelation
-      # is idempotent: a run that has already finished (`PROCESSED`/`ERROR`) or was
-      # already `CANCELED` is left unchanged and its current status is returned.
+      # Cancels in-flight journey runs, either every run sharing a cancelation token or
+      # one run by id. Use it to stop a sequence when the event resolves.
       sig do
         params(
           cancel_journey_request:
@@ -114,53 +128,82 @@ module Courier
               Courier::CancelJourneyRequest::ByCancelationToken::OrHash,
               Courier::CancelJourneyRequest::ByRunID::OrHash
             ),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::CancelJourneyResponse::Variants)
       end
       def cancel(
-        # Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of
+        # Body param: Request body for `POST /journeys/cancel`. Provide EXACTLY ONE of
         # `cancelation_token` (cancels every run associated with the token) or `run_id`
         # (cancels a single tenant-scoped run).
         cancel_journey_request:,
+        # 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
 
-      # Invoke a journey by id or alias to start a new run. The response includes a
-      # `runId` identifying the run.
+      # Starts a journey run for one user and returns a runId. Runs execute
+      # asynchronously, so the response arrives before any message is sent.
       sig do
         params(
           template_id: String,
           data: T::Hash[Symbol, T.anything],
           profile: T::Hash[Symbol, T.anything],
           user_id: String,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::JourneysInvokeResponse)
       end
       def invoke(
-        # A unique identifier representing the journey to be invoked. Accepts a Journey ID
-        # or Journey Alias.
+        # Path param: A unique identifier representing the journey to be invoked. Accepts
+        # a Journey ID or Journey Alias.
         template_id,
-        # Data payload passed to the journey. The expected shape can be predefined using
-        # the schema builder in the journey editor. This data is available in journey
-        # steps for condition evaluation and template variable interpolation. Can also
-        # contain user identifiers (user_id, userId, anonymousId) if not provided
-        # elsewhere.
+        # Body param: Data payload passed to the journey. The expected shape can be
+        # predefined using the schema builder in the journey editor. This data is
+        # available in journey steps for condition evaluation and template variable
+        # interpolation. Can also contain user identifiers (user_id, userId, anonymousId)
+        # if not provided elsewhere.
         data: nil,
-        # Profile data for the user. Can contain contact information (email,
+        # Body param: Profile data for the user. Can contain contact information (email,
         # phone_number), user identifiers (user_id, userId, anonymousId), or any custom
         # profile fields. Profile fields are merged with any existing stored profile for
         # the user. Include context.tenant_id to load a tenant-scoped profile for
         # multi-tenant scenarios.
         profile: nil,
-        # A unique identifier for the user. If not provided, the system will attempt to
-        # resolve the user identifier from profile or data objects.
+        # Body param: A unique identifier for the user. If not provided, the system will
+        # attempt to resolve the user identifier from profile or data objects.
         user_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
 
-      # List published versions of a journey, ordered most recent first.
+      # Lists a journey's published versions, most recent first, so you have a version
+      # id to roll back to. Paged by cursor.
       sig do
         params(
           template_id: String,
@@ -174,29 +217,40 @@ module Courier
       )
       end
 
-      # Publish the current draft as a new version. Body is optional; pass
-      # `{ "version": "vN" }` to roll back to a prior version instead. Returns 404 if
-      # the journey has no draft to publish.
+      # Publishes a journey's current draft as a new version, making it live for new
+      # runs. Pass a version instead to roll back to an earlier one.
       sig do
         params(
           template_id: String,
           version: String,
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::JourneyResponse)
       end
       def publish(
-        # Journey id
+        # Path param: Journey id
         template_id,
+        # Body param
         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 journey draft. Updates the working draft only; call
-      # `POST /journeys/{templateId}/publish` to make it live, or pass
-      # `state: "PUBLISHED"` in this request to publish immediately. Send-node
-      # `template` ids must already exist and be scoped to this journey, and node ids
-      # must not be claimed by another journey.
+      # Replaces a journey's working draft, leaving the published version live until you
+      # publish. Reach for this when editing a journey already running.
       sig do
         params(
           template_id: String,

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,