trycourier 4.21.0 → 4.23.0

data/rbi/courier/resources/broadcasts.rbi

@@ -0,0 +1,199 @@
+# typed: strong
+
+module Courier
+  module Resources
+    class Broadcasts
+      # Create a broadcast. Provisions a private notification template for the broadcast
+      # and returns the new broadcast in the draft state. Exactly one channel is
+      # required.
+      sig do
+        params(
+          channel: Courier::CreateBroadcastRequest::Channel::OrSymbol,
+          name: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def create(
+        # The single delivery channel for this broadcast.
+        channel:,
+        # Human-readable name.
+        name:,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a broadcast by ID. Archived broadcasts return 404.
+      sig do
+        params(
+          broadcast_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def retrieve(broadcast_id, request_options: {})
+      end
+
+      # Update a broadcast's name. Content is edited via the broadcast's notification
+      # template, not this endpoint.
+      sig do
+        params(
+          broadcast_id: String,
+          name: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def update(
+        broadcast_id,
+        # New human-readable name.
+        name:,
+        request_options: {}
+      )
+      end
+
+      # List broadcasts in your workspace. Cursor-paginated; returns broadcasts
+      # newest-first.
+      sig do
+        params(
+          cursor: T.nilable(String),
+          limit: Integer,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::BroadcastListResponse)
+      end
+      def list(
+        # Opaque pagination cursor from a previous response. Omit for the first page.
+        cursor: nil,
+        # Maximum number of results per page.
+        limit: nil,
+        request_options: {}
+      )
+      end
+
+      # Archive a broadcast. This is a soft delete — the archived broadcast is returned
+      # and no longer appears in list results.
+      sig do
+        params(
+          broadcast_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def archive(broadcast_id, request_options: {})
+      end
+
+      # Cancel a broadcast's pending schedule, returning it to the draft state. Only
+      # valid for a scheduled broadcast.
+      sig do
+        params(
+          broadcast_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def cancel(broadcast_id, request_options: {})
+      end
+
+      # Duplicate a broadcast (and its template) into a new draft named "{source name}
+      # (copy)".
+      sig do
+        params(
+          broadcast_id: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def duplicate(broadcast_id, request_options: {})
+      end
+
+      # Author the broadcast's content by replacing the draft elemental content of its
+      # private notification template. The draft is published automatically when the
+      # broadcast is sent or scheduled.
+      sig do
+        params(
+          broadcast_id: String,
+          content: Courier::NotificationContentPutRequest::Content::OrHash,
+          state: Courier::NotificationTemplateState::OrSymbol,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::NotificationContentMutationResponse)
+      end
+      def put_content(
+        broadcast_id,
+        # Elemental content payload. The server defaults `version` when omitted.
+        content:,
+        # Template state. Defaults to `DRAFT`.
+        state: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve the broadcast's content — the elemental content of its private
+      # notification template. Defaults to the working draft, since broadcast content is
+      # authored as a draft until the broadcast is sent.
+      sig do
+        params(
+          broadcast_id: String,
+          version: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::NotificationContentGetResponse)
+      end
+      def retrieve_content(
+        broadcast_id,
+        # Accepts `draft`, `published`, or a version string (e.g. `v001`). Defaults to
+        # `draft`.
+        version: nil,
+        request_options: {}
+      )
+      end
+
+      # Schedule a broadcast for a future send to a list or audience. Publishes the
+      # broadcast template first. Not allowed once the broadcast is sending or sent. For
+      # an immediate send use POST /broadcasts/{broadcastId}/send.
+      sig do
+        params(
+          broadcast_id: String,
+          recipient_id: String,
+          recipient_type:
+            Courier::ScheduleBroadcastRequest::RecipientType::OrSymbol,
+          scheduled_to: String,
+          timezone: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def schedule(
+        broadcast_id,
+        # ID of the target list or audience.
+        recipient_id:,
+        # Whether the broadcast targets a list or an audience.
+        recipient_type:,
+        # Wall-clock timestamp of the future send, no timezone offset (e.g.
+        # "2026-07-21T20:00:00"). The zone is given by `timezone`.
+        scheduled_to:,
+        # IANA timezone for the scheduled send (e.g. America/New_York).
+        timezone: nil,
+        request_options: {}
+      )
+      end
+
+      # Send a broadcast immediately to a list or audience. Publishes the broadcast
+      # template first. Not allowed once the broadcast is sending or sent.
+      sig do
+        params(
+          broadcast_id: String,
+          recipient_id: String,
+          recipient_type:
+            Courier::SendBroadcastRequest::RecipientType::OrSymbol,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(Courier::Broadcast)
+      end
+      def send_(
+        broadcast_id,
+        # ID of the target list or audience.
+        recipient_id:,
+        # Whether the broadcast targets a list or an audience.
+        recipient_type:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Courier::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

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,

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,