trycourier 4.20.0 → 4.22.0

data/rbi/courier/resources/audiences.rbi

@@ -2,8 +2,11 @@
 
 module Courier
   module Resources
+    # Define filter-based groups whose membership Courier recalculates as user
+    # profiles change.
     class Audiences
-      # Returns the specified audience by id.
+      # Returns one audience with its name, description, and the filter and AND or OR
+      # operator that decide which users belong to it.
       sig do
         params(
           audience_id: String,
@@ -17,7 +20,8 @@ module Courier
       )
       end
 
-      # Creates or updates audience.
+      # Creates or replaces an audience from a filter and an AND or OR operator.
+      # Membership recalculates automatically as profiles change.
       sig do
         params(
           audience_id: String,
@@ -46,7 +50,8 @@ module Courier
       )
       end
 
-      # Get the audiences associated with the authorization token.
+      # Returns the audiences in the workspace with paging. Audiences are filter-based
+      # groups that recalculate as user profiles change.
       sig do
         params(
           cursor: T.nilable(String),
@@ -60,7 +65,8 @@ module Courier
       )
       end
 
-      # Deletes the specified audience.
+      # Deletes an audience permanently, so update any caller sending to it by audience
+      # id first. Those sends fail once the audience is gone.
       sig do
         params(
           audience_id: String,
@@ -74,7 +80,8 @@ module Courier
       )
       end
 
-      # Get list of members of an audience.
+      # Returns the users currently matching an audience filter, with paging. Membership
+      # is recalculated, so results shift as profiles change.
       sig do
         params(
           audience_id: String,

data/rbi/courier/resources/audit_events.rbi

@@ -2,8 +2,10 @@
 
 module Courier
   module Resources
+    # Read the audit trail of configuration and access changes in your workspace.
     class AuditEvents
-      # Fetch a specific audit event by ID.
+      # Returns one audit event by id, including the actor who performed it, the target
+      # they changed, the source, the event type, and a timestamp.
       sig do
         params(
           audit_event_id: String,
@@ -17,7 +19,8 @@ module Courier
       )
       end
 
-      # Fetch the list of audit events
+      # Returns the workspace's audit event log with cursor paging. Each event records
+      # the actor, target, source, type, and timestamp of a change.
       sig do
         params(
           cursor: T.nilable(String),

data/rbi/courier/resources/auth.rbi

@@ -2,8 +2,12 @@
 
 module Courier
   module Resources
+    # Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the
+    # embedded designer — can call Courier as a single user. Server-side requests
+    # authenticate with your workspace API key instead.
     class Auth
-      # Returns a new access token.
+      # Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply
+      # the scope and an expires_in duration, both required.
       sig do
         params(
           expires_in: String,

data/rbi/courier/resources/automations/invoke.rbi

@@ -3,11 +3,11 @@
 module Courier
   module Resources
     class Automations
+      # Invoke a stored automation template or an ad hoc automation defined in the
+      # request.
       class Invoke
-        # Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a
-        # series of automation steps. For information about what steps are available,
-        # checkout the ad hoc automation guide
-        # [here](https://www.courier.com/docs/automations/steps/).
+        # Runs a series of automation steps supplied inline, without a saved template, and
+        # returns a runId.
         sig do
           params(
             automation:
@@ -17,21 +17,42 @@ module Courier
             profile: T.nilable(T::Hash[Symbol, T.anything]),
             recipient: T.nilable(String),
             template: T.nilable(String),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::AutomationInvokeResponse)
         end
         def invoke_ad_hoc(
+          # Body param
           automation:,
+          # Body param
           brand: nil,
+          # Body param
           data: nil,
+          # Body param
           profile: nil,
+          # Body param
           recipient: nil,
+          # Body param
           template: 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
 
-        # Invoke an automation run from an automation template.
+        # Starts an automation run from a saved template for one recipient, with optional
+        # data and profile, and returns a runId.
         sig do
           params(
             template_id: String,
@@ -40,18 +61,38 @@ module Courier
             data: T.nilable(T::Hash[Symbol, T.anything]),
             profile: T.nilable(T::Hash[Symbol, T.anything]),
             template: T.nilable(String),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::AutomationInvokeResponse)
         end
         def invoke_by_template(
-          # A unique identifier representing the automation template to be invoked. This
-          # could be the Automation Template ID or the Automation Template Alias.
+          # Path param: A unique identifier representing the automation template to be
+          # invoked. This could be the Automation Template ID or the Automation Template
+          # Alias.
           template_id,
+          # Body param
           recipient:,
+          # Body param
           brand: nil,
+          # Body param
           data: nil,
+          # Body param
           profile: nil,
+          # Body param
           template: nil,
+          # Header param: A unique key that makes this request idempotent. If Courier
+          # receives another request with the same `Idempotency-Key`, it returns the stored
+          # response from the first request without performing the operation again
+          # (including the original status code and any error). Use it to safely retry
+          # `POST` requests after network failures without risking duplicate sends. The key
+          # is scoped to this endpoint.
+          idempotency_key: nil,
+          # Header param: How long the idempotency key remains valid, as a Unix epoch
+          # timestamp in seconds or an ISO 8601 date string. Only applies when
+          # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+          # maximum is 1 year.
+          x_idempotency_expiration: nil,
           request_options: {}
         )
         end

data/rbi/courier/resources/automations.rbi

@@ -2,11 +2,16 @@
 
 module Courier
   module Resources
+    # Invoke a stored automation template or an ad hoc automation defined in the
+    # request.
     class Automations
+      # Invoke a stored automation template or an ad hoc automation defined in the
+      # request.
       sig { returns(Courier::Resources::Automations::Invoke) }
       attr_reader :invoke
 
-      # Get the list of automations.
+      # Lists the workspace's saved automation templates, each with its id and a cursor
+      # for paging to the next page of results.
       sig do
         params(
           cursor: String,

data/rbi/courier/resources/brands.rbi

@@ -2,22 +2,49 @@
 
 module Courier
   module Resources
+    # Manage the logos, colors, and layout that give the templates you send a
+    # consistent look.
     class Brands
-      # Create a new brand. Requires `name` and `settings` (with at least
-      # `colors.primary` and `colors.secondary`).
+      # Creates a brand from a name and settings, including primary and secondary
+      # colors. Brands supply the logo, colors, and styling that templates render with.
       sig do
         params(
           name: String,
           settings: Courier::BrandSettings::OrHash,
           id: T.nilable(String),
           snippets: T.nilable(Courier::BrandSnippets::OrHash),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Brand)
       end
-      def create(name:, settings:, id: nil, snippets: nil, request_options: {})
+      def create(
+        # Body param
+        name:,
+        # Body param
+        settings:,
+        # Body param
+        id: nil,
+        # Body param
+        snippets: 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 specific brand by brand ID.
+      # Returns one brand by id, including its colors, logo and styling settings,
+      # Handlebars snippets, and published version.
       sig do
         params(
           brand_id: String,
@@ -31,7 +58,8 @@ module Courier
       )
       end
 
-      # Replace an existing brand with the supplied values.
+      # Replaces a brand with the values you supply, so send the complete settings and
+      # snippets rather than only the fields you want changed.
       sig do
         params(
           brand_id: String,
@@ -52,7 +80,8 @@ module Courier
       )
       end
 
-      # Get the list of brands.
+      # Lists the workspace's brands. Every entry carries its name, styling settings,
+      # snippets, and published version.
       sig do
         params(
           cursor: T.nilable(String),
@@ -66,7 +95,8 @@ module Courier
       )
       end
 
-      # Delete a brand by brand ID.
+      # Deletes a brand by id. Reassign any template or tenant that references it before
+      # deleting to keep their styling intact.
       sig do
         params(
           brand_id: String,

data/rbi/courier/resources/digests/schedules.rbi

@@ -3,10 +3,11 @@
 module Courier
   module Resources
     class Digests
+      # Inspect what has accumulated in a digest schedule and release a digest ahead of
+      # its next scheduled delivery.
       class Schedules
-        # List the digest instances for a schedule. Each instance represents the events
-        # accumulated for a single user against the schedule, and can be used to monitor
-        # digest accumulation before the digest is released.
+        # Returns the digest instances for a schedule, one per user, with cursor paging.
+        # Use it to see what has accumulated before a digest releases.
         sig do
           params(
             schedule_id: String,

data/rbi/courier/resources/digests.rbi

@@ -3,6 +3,8 @@
 module Courier
   module Resources
     class Digests
+      # Inspect what has accumulated in a digest schedule and release a digest ahead of
+      # its next scheduled delivery.
       sig { returns(Courier::Resources::Digests::Schedules) }
       attr_reader :schedules
 

data/rbi/courier/resources/inbound.rbi

@@ -2,8 +2,10 @@
 
 module Courier
   module Resources
+    # Record an inbound event that triggers the journeys and automations mapped to it.
     class Inbound
-      # Courier Track Event
+      # Records an inbound event that can trigger a journey. Requires an event name, a
+      # messageId you generate, a type, and a properties object.
       sig do
         params(
           event: String,

data/rbi/courier/resources/inbox/messages.rbi

@@ -0,0 +1,44 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Inbox
+      # Manage the messages in a user's in-app inbox.
+      class Messages
+        # Delete a user's inbox message. The message is removed from every inbox read (it
+        # stops appearing in the recipient's Inbox); it can be restored.
+        sig do
+          params(
+            message_id: String,
+            request_options: Courier::RequestOptions::OrHash
+          ).void
+        end
+        def delete(
+          # The message ID of the inbox message to delete.
+          message_id,
+          request_options: {}
+        )
+        end
+
+        # Restore a previously deleted inbox message.
+        sig do
+          params(
+            message_id: String,
+            request_options: Courier::RequestOptions::OrHash
+          ).void
+        end
+        def restore(
+          # The message ID of the inbox message to restore.
+          message_id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Courier::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/courier/resources/inbox.rbi

@@ -0,0 +1,16 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Inbox
+      # Manage the messages in a user's in-app inbox.
+      sig { returns(Courier::Resources::Inbox::Messages) }
+      attr_reader :messages
+
+      # @api private
+      sig { params(client: Courier::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/courier/resources/journeys/templates.rbi

@@ -3,6 +3,8 @@
 module Courier
   module Resources
     class Journeys
+      # Build, version, publish, invoke, and cancel multi-step notification workflows,
+      # along with the templates scoped to them.
       class Templates
         # Create a notification template scoped to this journey. Defaults to `DRAFT`
         # state; pass `state: "PUBLISHED"` to publish on create.
@@ -14,23 +16,40 @@ module Courier
               Courier::JourneyTemplateCreateRequest::Notification::OrHash,
             provider_key: String,
             state: String,
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::JourneyTemplateGetResponse)
         end
         def create(
-          # Journey id
+          # Path param: Journey id
           template_id,
+          # Body param
           channel:,
+          # Body param
           notification:,
+          # Body param
           provider_key: nil,
+          # Body param
           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
 
-        # Fetch a journey-scoped notification template by id. Pass `?version=draft`
-        # (default `published`) to retrieve the working draft, or `?version=vN` for a
-        # historical version.
+        # Returns a journey's own notification template with its name, brand, subscription
+        # topic, and content. Defaults to the published version.
         sig do
           params(
             notification_id: String,
@@ -68,8 +87,8 @@ module Courier
         )
         end
 
-        # Archive the journey-scoped notification template. Archived templates cannot be
-        # sent.
+        # Archives one journey's notification template, preventing further sends. Detach
+        # any send node referencing it beforehand.
         sig do
           params(
             notification_id: String,
@@ -86,8 +105,8 @@ module Courier
         )
         end
 
-        # List published versions of the journey-scoped notification template, ordered
-        # most recent first.
+        # Lists the published versions of a template that belongs to a journey, most
+        # recent first. Paged by cursor.
         sig do
           params(
             notification_id: String,
@@ -104,14 +123,15 @@ module Courier
         )
         end
 
-        # Publish the current draft of the journey-scoped notification template as a new
-        # version. Optionally roll back to a prior version by passing
-        # `{ "version": "vN" }`.
+        # Publishes a journey-scoped template's draft as a new version. Pass a version
+        # instead to roll back the template to an earlier publish.
         sig do
           params(
             notification_id: String,
             template_id: String,
             version: String,
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).void
         end
@@ -122,6 +142,18 @@ module Courier
           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
@@ -179,7 +211,8 @@ module Courier
         )
         end
 
-        # Replace the journey-scoped notification template draft.
+        # Replaces the draft content of one journey's notification template. Publish it
+        # before send nodes referencing it render the change.
         sig do
           params(
             notification_id: String,
@@ -203,11 +236,8 @@ module Courier
         )
         end
 
-        # Retrieve the elemental content of a journey-scoped notification template. The
-        # response contains the versioned elements along with their content checksums,
-        # which can be used to detect changes between versions. Pass `?version=draft`
-        # (default `published`) to retrieve the working draft, or `?version=vN` for a
-        # historical version.
+        # Returns the Elemental elements and version of a journey-scoped template's
+        # content. Compare versions to see what changed between publishes.
         sig do
           params(
             notification_id: String,