trycourier 4.21.0 → 4.23.0

data/lib/courier/resources/broadcasts.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+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.
+      #
+      # @overload create(channel:, name:, request_options: {})
+      #
+      # @param channel [Symbol, Courier::Models::CreateBroadcastRequest::Channel] The single delivery channel for this broadcast.
+      #
+      # @param name [String] Human-readable name.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastCreateParams
+      def create(params)
+        parsed, options = Courier::BroadcastCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "broadcasts",
+          body: parsed,
+          model: Courier::Broadcast,
+          options: options
+        )
+      end
+
+      # Retrieve a broadcast by ID. Archived broadcasts return 404.
+      #
+      # @overload retrieve(broadcast_id, request_options: {})
+      #
+      # @param broadcast_id [String]
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastRetrieveParams
+      def retrieve(broadcast_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["broadcasts/%1$s", broadcast_id],
+          model: Courier::Broadcast,
+          options: params[:request_options]
+        )
+      end
+
+      # Update a broadcast's name. Content is edited via the broadcast's notification
+      # template, not this endpoint.
+      #
+      # @overload update(broadcast_id, name:, request_options: {})
+      #
+      # @param broadcast_id [String]
+      #
+      # @param name [String] New human-readable name.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastUpdateParams
+      def update(broadcast_id, params)
+        parsed, options = Courier::BroadcastUpdateParams.dump_request(params)
+        @client.request(
+          method: :put,
+          path: ["broadcasts/%1$s", broadcast_id],
+          body: parsed,
+          model: Courier::Broadcast,
+          options: options
+        )
+      end
+
+      # List broadcasts in your workspace. Cursor-paginated; returns broadcasts
+      # newest-first.
+      #
+      # @overload list(cursor: nil, limit: nil, request_options: {})
+      #
+      # @param cursor [String, nil] Opaque pagination cursor from a previous response. Omit for the first page.
+      #
+      # @param limit [Integer] Maximum number of results per page.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::BroadcastListResponse]
+      #
+      # @see Courier::Models::BroadcastListParams
+      def list(params = {})
+        parsed, options = Courier::BroadcastListParams.dump_request(params)
+        query = Courier::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "broadcasts",
+          query: query,
+          model: Courier::BroadcastListResponse,
+          options: options
+        )
+      end
+
+      # Archive a broadcast. This is a soft delete — the archived broadcast is returned
+      # and no longer appears in list results.
+      #
+      # @overload archive(broadcast_id, request_options: {})
+      #
+      # @param broadcast_id [String]
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastArchiveParams
+      def archive(broadcast_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["broadcasts/%1$s", broadcast_id],
+          model: Courier::Broadcast,
+          options: params[:request_options]
+        )
+      end
+
+      # Cancel a broadcast's pending schedule, returning it to the draft state. Only
+      # valid for a scheduled broadcast.
+      #
+      # @overload cancel(broadcast_id, request_options: {})
+      #
+      # @param broadcast_id [String]
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastCancelParams
+      def cancel(broadcast_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["broadcasts/%1$s/cancel", broadcast_id],
+          model: Courier::Broadcast,
+          options: params[:request_options]
+        )
+      end
+
+      # Duplicate a broadcast (and its template) into a new draft named "{source name}
+      # (copy)".
+      #
+      # @overload duplicate(broadcast_id, request_options: {})
+      #
+      # @param broadcast_id [String]
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastDuplicateParams
+      def duplicate(broadcast_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["broadcasts/%1$s/duplicate", broadcast_id],
+          model: Courier::Broadcast,
+          options: params[: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.
+      #
+      # @overload put_content(broadcast_id, content:, state: nil, request_options: {})
+      #
+      # @param broadcast_id [String]
+      #
+      # @param content [Courier::Models::NotificationContentPutRequest::Content] Elemental content payload. The server defaults `version` when omitted.
+      #
+      # @param state [Symbol, Courier::Models::NotificationTemplateState] Template state. Defaults to `DRAFT`.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::NotificationContentMutationResponse]
+      #
+      # @see Courier::Models::BroadcastPutContentParams
+      def put_content(broadcast_id, params)
+        parsed, options = Courier::BroadcastPutContentParams.dump_request(params)
+        @client.request(
+          method: :put,
+          path: ["broadcasts/%1$s/content", broadcast_id],
+          body: parsed,
+          model: Courier::NotificationContentMutationResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::BroadcastRetrieveContentParams} for more details.
+      #
+      # 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.
+      #
+      # @overload retrieve_content(broadcast_id, version: nil, request_options: {})
+      #
+      # @param broadcast_id [String]
+      #
+      # @param version [String] Accepts `draft`, `published`, or a version string (e.g. `v001`). Defaults to `dr
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::NotificationContentGetResponse]
+      #
+      # @see Courier::Models::BroadcastRetrieveContentParams
+      def retrieve_content(broadcast_id, params = {})
+        parsed, options = Courier::BroadcastRetrieveContentParams.dump_request(params)
+        query = Courier::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["broadcasts/%1$s/content", broadcast_id],
+          query: query,
+          model: Courier::NotificationContentGetResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::BroadcastScheduleParams} for more details.
+      #
+      # 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.
+      #
+      # @overload schedule(broadcast_id, recipient_id:, recipient_type:, scheduled_to:, timezone: nil, request_options: {})
+      #
+      # @param broadcast_id [String]
+      #
+      # @param recipient_id [String] ID of the target list or audience.
+      #
+      # @param recipient_type [Symbol, Courier::Models::ScheduleBroadcastRequest::RecipientType] Whether the broadcast targets a list or an audience.
+      #
+      # @param scheduled_to [String] Wall-clock timestamp of the future send, no timezone offset (e.g. "2026-07-21T20
+      #
+      # @param timezone [String] IANA timezone for the scheduled send (e.g. America/New_York).
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastScheduleParams
+      def schedule(broadcast_id, params)
+        parsed, options = Courier::BroadcastScheduleParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["broadcasts/%1$s/schedule", broadcast_id],
+          body: parsed,
+          model: Courier::Broadcast,
+          options: 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.
+      #
+      # @overload send_(broadcast_id, recipient_id:, recipient_type:, request_options: {})
+      #
+      # @param broadcast_id [String]
+      #
+      # @param recipient_id [String] ID of the target list or audience.
+      #
+      # @param recipient_type [Symbol, Courier::Models::SendBroadcastRequest::RecipientType] Whether the broadcast targets a list or an audience.
+      #
+      # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Courier::Models::Broadcast]
+      #
+      # @see Courier::Models::BroadcastSendParams
+      def send_(broadcast_id, params)
+        parsed, options = Courier::BroadcastSendParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["broadcasts/%1$s/send", broadcast_id],
+          body: parsed,
+          model: Courier::Broadcast,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Courier::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/courier/resources/digests/schedules.rb

@@ -3,13 +3,14 @@
 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
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Digests::ScheduleListInstancesParams} for more details.
         #
-        # 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.
         #
         # @overload list_instances(schedule_id, cursor: nil, limit: nil, request_options: {})
         #

data/lib/courier/resources/digests.rb

@@ -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.
       # @return [Courier::Resources::Digests::Schedules]
       attr_reader :schedules
 

data/lib/courier/resources/inbound.rb

@@ -2,11 +2,13 @@
 
 module Courier
   module Resources
+    # Record an inbound event that triggers the journeys and automations mapped to it.
     class Inbound
       # Some parameter documentations has been truncated, see
       # {Courier::Models::InboundTrackEventParams} for more details.
       #
-      # 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.
       #
       # @overload track_event(event:, message_id:, properties:, type:, user_id: nil, request_options: {})
       #

data/lib/courier/resources/inbox/messages.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+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.
+        #
+        # @overload delete(message_id, request_options: {})
+        #
+        # @param message_id [String] The message ID of the inbox message to delete.
+        #
+        # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Courier::Models::Inbox::MessageDeleteParams
+        def delete(message_id, params = {})
+          @client.request(
+            method: :delete,
+            path: ["inbox/messages/%1$s", message_id],
+            model: NilClass,
+            options: params[:request_options]
+          )
+        end
+
+        # Restore a previously deleted inbox message.
+        #
+        # @overload restore(message_id, request_options: {})
+        #
+        # @param message_id [String] The message ID of the inbox message to restore.
+        #
+        # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Courier::Models::Inbox::MessageRestoreParams
+        def restore(message_id, params = {})
+          @client.request(
+            method: :put,
+            path: ["inbox/messages/%1$s/restore", message_id],
+            model: NilClass,
+            options: params[:request_options]
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Courier::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/courier/resources/inbox.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Courier
+  module Resources
+    class Inbox
+      # Manage the messages in a user's in-app inbox.
+      # @return [Courier::Resources::Inbox::Messages]
+      attr_reader :messages
+
+      # @api private
+      #
+      # @param client [Courier::Client]
+      def initialize(client:)
+        @client = client
+        @messages = Courier::Resources::Inbox::Messages.new(client: client)
+      end
+    end
+  end
+end

data/lib/courier/resources/journeys/templates.rb

@@ -3,21 +3,30 @@
 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
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Journeys::TemplateCreateParams} for more details.
+        #
         # Create a notification template scoped to this journey. Defaults to `DRAFT`
         # state; pass `state: "PUBLISHED"` to publish on create.
         #
-        # @overload create(template_id, channel:, notification:, provider_key: nil, state: nil, request_options: {})
+        # @overload create(template_id, channel:, notification:, provider_key: nil, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #
-        # @param template_id [String] Journey id
+        # @param template_id [String] Path param: Journey id
         #
-        # @param channel [String]
+        # @param channel [String] Body param
         #
-        # @param notification [Courier::Models::JourneyTemplateCreateRequest::Notification]
+        # @param notification [Courier::Models::JourneyTemplateCreateRequest::Notification] Body param
+        #
+        # @param provider_key [String] Body param
+        #
+        # @param state [String] Body param
         #
-        # @param provider_key [String]
+        # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
         #
-        # @param state [String]
+        # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
         #
         # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -26,18 +35,20 @@ module Courier
         # @see Courier::Models::Journeys::TemplateCreateParams
         def create(template_id, params)
           parsed, options = Courier::Journeys::TemplateCreateParams.dump_request(params)
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: ["journeys/%1$s/templates", template_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Courier::JourneyTemplateGetResponse,
             options: 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.
         #
         # @overload retrieve(notification_id, template_id:, request_options: {})
         #
@@ -92,8 +103,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.
         #
         # @overload archive(notification_id, template_id:, request_options: {})
         #
@@ -120,8 +131,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.
         #
         # @overload list_versions(notification_id, template_id:, request_options: {})
         #
@@ -148,11 +159,13 @@ 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" }`.
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Journeys::TemplatePublishParams} for more details.
+        #
+        # Publishes a journey-scoped template's draft as a new version. Pass a version
+        # instead to roll back the template to an earlier publish.
         #
-        # @overload publish(notification_id, template_id:, version: nil, request_options: {})
+        # @overload publish(notification_id, template_id:, version: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #
         # @param notification_id [String] Path param: Notification template id
         #
@@ -160,6 +173,10 @@ module Courier
         #
         # @param version [String] Body param
         #
+        # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+        #
+        # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
+        #
         # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [nil]
@@ -171,10 +188,13 @@ module Courier
             parsed.delete(:template_id) do
               raise ArgumentError.new("missing required path argument #{_1}")
             end
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: ["journeys/%1$s/templates/%2$s/publish", template_id, notification_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: NilClass,
             options: options
           )
@@ -255,7 +275,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.
         #
         # @overload replace(notification_id, template_id:, notification:, state: nil, request_options: {})
         #
@@ -290,11 +311,8 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Journeys::TemplateRetrieveContentParams} for more details.
         #
-        # 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.
         #
         # @overload retrieve_content(notification_id, template_id:, version: nil, request_options: {})
         #