trycourier 6.4.3 → 6.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8b8d37f136533933d8866b7f9c65690f4a7f97c858fcfe8a59b22f9207258e3
-  data.tar.gz: 5109857a74cebd79366d2cfe314cacebef0c42e6501cfc225e294a7c03e3b9bf
+  metadata.gz: b85383a5a075aec281248a33e3baeb163257dcc14a786a0faed05bafa02dd5db
+  data.tar.gz: f4144cce9c3b08a4b62579c54cf69a7d3234e21e61f74358ab8ac6d1702d2f57
 SHA512:
-  metadata.gz: 999317f439a918452c23d3e626c1412afc02f921e26d5323d8c56d46d17bff8705edf5ef69c98c47eeb0247dad214e6d74e8c62241c63295da98517e58b5b1fc
-  data.tar.gz: 28ed1d47648060561af1be5579193eb16d52c40a8d460919f046d9617e5d45ae2b34dadc16418822e8f327e442c456e1ea5cd81b3deba123ce95dcdc12346187
+  metadata.gz: 344f0da30f2d93dbcad8f178ac74528c4b30209b0f4c67c8fcadd3fab10a1410d313d5467dc84c267076da4ce24387fd47602087e23dcb233eade584be12350e
+  data.tar.gz: f10b02d48f1aee2d14d0e538eaea4125eb2099262af4cd0d5a8b391342d974f6a73094f11ad8ea50094392fae9d49de32d902804ac659218f8047e7e0a512f70

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [6.4.4](https://github.com/trycourier/courier-ruby/compare/v6.4.3...v6.4.4) (2026-09-03)
+
+
+### Documentation
+
+* **api:** document the channel-block requirement on template creation ([#146](https://github.com/trycourier/courier-ruby/issues/146)) ([95749c6](https://github.com/trycourier/courier-ruby/commit/95749c6db1bd5e1b07d28d1f59970652b5cb2c49))
+
 ## [6.4.3](https://github.com/trycourier/courier-ruby/compare/v6.4.2...v6.4.3) (2026-08-29)
 
 

data/README.md

@@ -9,7 +9,7 @@ Add the gem to your `Gemfile`:
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "trycourier", "~> 6.4.3"
+gem "trycourier", "~> 6.4.4"
 ```
 
 <!-- x-release-please-end -->

data/lib/courier/models/elemental_channel_node.rb

@@ -10,6 +10,16 @@ module Courier
       #   @return [String, nil]
       optional :channel, String
 
+      # @!attribute elements
+      #   An array of elements to apply to the channel. If `raw` has not been specified,
+      #   `elements` is `required`. Channel elements cannot nest, so these are any node
+      #   except another channel block.
+      #
+      #   @return [Array<Courier::Models::ElementalNodeNonChannel::UnionMember0, Courier::Models::ElementalNodeNonChannel::UnionMember1, Courier::Models::ElementalNodeNonChannel::UnionMember2, Courier::Models::ElementalNodeNonChannel::UnionMember3, Courier::Models::ElementalNodeNonChannel::UnionMember4, Courier::Models::ElementalNodeNonChannel::UnionMember5, Courier::Models::ElementalNodeNonChannel::UnionMember6>, nil]
+      optional :elements,
+               -> { Courier::Internal::Type::ArrayOf[union: Courier::ElementalNodeNonChannel] },
+               nil?: true
+
       # @!attribute font_size
       #   Email only. Document-level base font size (CSS px, e.g. `16px`) for body content
       #   — text, quote, list and action button labels. Heading styles (`h1`/`h2`/`h3`)
@@ -39,7 +49,7 @@ module Courier
       #   @return [Hash{Symbol=>Object}, nil]
       optional :raw, Courier::Internal::Type::HashOf[Courier::Internal::Type::Unknown], nil?: true
 
-      # @!method initialize(channel: nil, font_size: nil, line_height: nil, padding: nil, raw: nil)
+      # @!method initialize(channel: nil, elements: nil, font_size: nil, line_height: nil, padding: nil, raw: nil)
       #   Some parameter documentations has been truncated, see
       #   {Courier::Models::ElementalChannelNode} for more details.
       #
@@ -56,6 +66,8 @@ module Courier
       #
       #   @param channel [String] The channel the contents of this element should be applied to. Can be `email`, `
       #
+      #   @param elements [Array<Courier::Models::ElementalNodeNonChannel::UnionMember0, Courier::Models::ElementalNodeNonChannel::UnionMember1, Courier::Models::ElementalNodeNonChannel::UnionMember2, Courier::Models::ElementalNodeNonChannel::UnionMember3, Courier::Models::ElementalNodeNonChannel::UnionMember4, Courier::Models::ElementalNodeNonChannel::UnionMember5, Courier::Models::ElementalNodeNonChannel::UnionMember6>, nil] An array of elements to apply to the channel. If `raw` has not been
+      #
       #   @param font_size [String, nil] Email only. Document-level base font size (CSS px, e.g. `16px`) for body content
       #
       #   @param line_height [String, nil] Email only. Document-level line height (CSS px or unitless multiplier, e.g. `24p

data/lib/courier/models/elemental_node_non_channel.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Courier
+  module Models
+    # Any Elemental node except a channel block. Channel elements are only valid as
+    # top-level elements, so the `elements` nested inside one can never be another
+    # channel. Keeping this union channel-free also keeps the schema acyclic; a
+    # recursive `$ref` here breaks the generated Python models.
+    module ElementalNodeNonChannel
+      extend Courier::Internal::Type::Union
+
+      # Represents a body of text to be rendered inside of the notification.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember0 }
+
+      # The meta element contains information describing the notification that may  be used by a particular channel or provider. One important field is the title  field which will be used as the title for channels that support it.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember1 }
+
+      # Used to embed an image into the notification.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember2 }
+
+      # Allows the user to execute an action. Can be a button or a link.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember3 }
+
+      # Renders a dividing line between elements.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember4 }
+
+      # Renders a quote block.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember5 }
+
+      # Raw HTML string inside an Elemental document. When rendering a message, this node is turned into output only for the email channel; for other channels it produces no blocks.
+      variant -> { Courier::ElementalNodeNonChannel::UnionMember6 }
+
+      class UnionMember0 < Courier::Models::ElementalTextNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember0::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember0::Type }
+
+        # @!method initialize(type: nil)
+        #   Represents a body of text to be rendered inside of the notification.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember0::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          TEXT = :text
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember1 < Courier::Models::ElementalMetaNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember1::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember1::Type }
+
+        # @!method initialize(type: nil)
+        #   The meta element contains information describing the notification that may be
+        #   used by a particular channel or provider. One important field is the title field
+        #   which will be used as the title for channels that support it.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember1::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          META = :meta
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember2 < Courier::Models::ElementalImageNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember2::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember2::Type }
+
+        # @!method initialize(type: nil)
+        #   Used to embed an image into the notification.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember2::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          IMAGE = :image
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember3 < Courier::Models::ElementalActionNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember3::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember3::Type }
+
+        # @!method initialize(type: nil)
+        #   Allows the user to execute an action. Can be a button or a link.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember3::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          ACTION = :action
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember4 < Courier::Models::ElementalDividerNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember4::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember4::Type }
+
+        # @!method initialize(type: nil)
+        #   Renders a dividing line between elements.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember4::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          DIVIDER = :divider
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember5 < Courier::Models::ElementalQuoteNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember5::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember5::Type }
+
+        # @!method initialize(type: nil)
+        #   Renders a quote block.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember5::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          QUOTE = :quote
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      class UnionMember6 < Courier::Models::ElementalHTMLNode
+        # @!attribute type
+        #
+        #   @return [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember6::Type, nil]
+        optional :type, enum: -> { Courier::ElementalNodeNonChannel::UnionMember6::Type }
+
+        # @!method initialize(type: nil)
+        #   Raw HTML string inside an Elemental document. When rendering a message, this
+        #   node is turned into output only for the email channel; for other channels it
+        #   produces no blocks.
+        #
+        #   @param type [Symbol, Courier::Models::ElementalNodeNonChannel::UnionMember6::Type]
+
+        module Type
+          extend Courier::Internal::Type::Enum
+
+          HTML = :html
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+
+      # @!method self.variants
+      #   @return [Array(Courier::Models::ElementalNodeNonChannel::UnionMember0, Courier::Models::ElementalNodeNonChannel::UnionMember1, Courier::Models::ElementalNodeNonChannel::UnionMember2, Courier::Models::ElementalNodeNonChannel::UnionMember3, Courier::Models::ElementalNodeNonChannel::UnionMember4, Courier::Models::ElementalNodeNonChannel::UnionMember5, Courier::Models::ElementalNodeNonChannel::UnionMember6)]
+    end
+  end
+end

data/lib/courier/models/notification_template_update_request.rb

@@ -21,9 +21,12 @@ module Courier
       #   Some parameter documentations has been truncated, see
       #   {Courier::Models::NotificationTemplateUpdateRequest} for more details.
       #
-      #   Request body for replacing a notification template. Same shape as create. All
-      #   fields required (PUT = full replacement), except `alias`, whose omission means
-      #   "leave the existing aliases alone".
+      #   Request body for replacing a notification template. All fields are required,
+      #   since `PUT` is a full replacement, except `alias`, whose omission leaves the
+      #   existing aliases in place. Unlike `NotificationTemplateCreateRequest`,
+      #   `notification.content` is not required to place its elements inside a channel
+      #   block: the requirement applies to creation only, so templates already stored
+      #   without one stay editable.
       #
       #   @param notification [Courier::Models::NotificationTemplateWritePayload] Template fields accepted in POST and PUT request bodies, nested under a `notific
       #

data/lib/courier/models.rb

@@ -227,6 +227,8 @@ module Courier
 
   ElementalNode = Courier::Models::ElementalNode
 
+  ElementalNodeNonChannel = Courier::Models::ElementalNodeNonChannel
+
   ElementalQuoteNode = Courier::Models::ElementalQuoteNode
 
   ElementalQuoteNodeWithType = Courier::Models::ElementalQuoteNodeWithType

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

@@ -12,6 +12,13 @@ module Courier
         # Create a notification template scoped to this journey. Defaults to `DRAFT`
         # state; pass `state: "PUBLISHED"` to publish on create.
         #
+        # The content tree must contain exactly one channel block whose `channel` matches
+        # the `channel` on the request — a journey-scoped template carries a single
+        # channel. Top-level elements, or a block for a different channel, return `400`.
+        # The template designer renders only the channel block matching the tab it draws,
+        # so content stored without one cannot be opened. An empty `elements` array is
+        # accepted.
+        #
         # @overload create(template_id, channel:, notification:, provider_key: nil, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #
         # @param template_id [String] Path param: Journey id

data/lib/courier/resources/notifications.rb

@@ -16,6 +16,16 @@ module Courier
       # Create a notification template. Requires all fields in the notification object.
       # Templates are created in draft state by default.
       #
+      # Content must place its elements inside a channel block —
+      # `{ "type": "channel", "channel": "email", "elements": [...] }` — or the request
+      # returns `400`. The template designer renders only the channel block matching the
+      # tab it draws, so content stored without one cannot be opened. An empty
+      # `elements` array is accepted, and the requirement applies to creation only:
+      # `PUT /notifications/{id}` still accepts unwrapped content. Note this endpoint
+      # takes versioned content only — the `{ title, body }` shorthand accepted by
+      # `/send` is rejected here with an `invalid_request_error` on
+      # `notification.content.version`.
+      #
       # @overload create(notification:, state: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
       #
       # @param notification [Courier::Models::NotificationTemplateWritePayload] Body param: Template fields accepted in POST and PUT request bodies, nested unde

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

@@ -135,6 +135,16 @@ module Courier
         # Creates or updates a notification template scoped to one tenant, letting a
         # tenant override the content the workspace template would send.
         #
+        # This is an upsert: it creates when the tenant has no template under
+        # `template_id`, and updates when it does. On the create half, content must place
+        # its elements inside a channel block —
+        # `{ "type": "channel", "channel": "email", "elements": [...] }` — or the request
+        # returns `400`. The template designer renders only the channel block matching the
+        # tab it draws, so content stored without one cannot be opened. An empty
+        # `elements` array is accepted, as is the `{ title, body }` shorthand, which has
+        # no elements to wrap. Updates are not checked, so tenant templates already stored
+        # without a wrapper stay editable.
+        #
         # @overload replace(template_id, tenant_id:, template:, published: nil, request_options: {})
         #
         # @param template_id [String] Path param: Id of the template to be created or updated.

data/lib/courier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Courier
-  VERSION = "6.4.3"
+  VERSION = "6.4.4"
 end

data/lib/courier.rb

@@ -189,6 +189,7 @@ require_relative "courier/models/elemental_html_node_with_type"
 require_relative "courier/models/elemental_image_node_with_type"
 require_relative "courier/models/elemental_meta_node_with_type"
 require_relative "courier/models/elemental_node"
+require_relative "courier/models/elemental_node_non_channel"
 require_relative "courier/models/elemental_quote_node_with_type"
 require_relative "courier/models/elemental_text_node_with_type"
 require_relative "courier/models/element_with_checksums"

data/rbi/courier/models/elemental_channel_node.rbi

@@ -16,6 +16,28 @@ module Courier
       sig { params(channel: String).void }
       attr_writer :channel
 
+      # An array of elements to apply to the channel. If `raw` has not been specified,
+      # `elements` is `required`. Channel elements cannot nest, so these are any node
+      # except another channel block.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[
+              T.any(
+                Courier::ElementalNodeNonChannel::UnionMember0,
+                Courier::ElementalNodeNonChannel::UnionMember1,
+                Courier::ElementalNodeNonChannel::UnionMember2,
+                Courier::ElementalNodeNonChannel::UnionMember3,
+                Courier::ElementalNodeNonChannel::UnionMember4,
+                Courier::ElementalNodeNonChannel::UnionMember5,
+                Courier::ElementalNodeNonChannel::UnionMember6
+              )
+            ]
+          )
+        )
+      end
+      attr_accessor :elements
+
       # Email only. Document-level base font size (CSS px, e.g. `16px`) for body content
       # — text, quote, list and action button labels. Heading styles (`h1`/`h2`/`h3`)
       # and `subtext` keep their preset sizes.
@@ -50,6 +72,20 @@ module Courier
       sig do
         params(
           channel: String,
+          elements:
+            T.nilable(
+              T::Array[
+                T.any(
+                  Courier::ElementalNodeNonChannel::UnionMember0::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember1::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember2::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember3::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember4::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember5::OrHash,
+                  Courier::ElementalNodeNonChannel::UnionMember6::OrHash
+                )
+              ]
+            ),
           font_size: T.nilable(String),
           line_height: T.nilable(String),
           padding: T.nilable(String),
@@ -60,6 +96,10 @@ module Courier
         # The channel the contents of this element should be applied to. Can be `email`,
         # `push`, `direct_message`, `sms` or a provider such as slack
         channel: nil,
+        # An array of elements to apply to the channel. If `raw` has not been specified,
+        # `elements` is `required`. Channel elements cannot nest, so these are any node
+        # except another channel block.
+        elements: nil,
         # Email only. Document-level base font size (CSS px, e.g. `16px`) for body content
         # — text, quote, list and action button labels. Heading styles (`h1`/`h2`/`h3`)
         # and `subtext` keep their preset sizes.
@@ -80,6 +120,20 @@ module Courier
         override.returns(
           {
             channel: String,
+            elements:
+              T.nilable(
+                T::Array[
+                  T.any(
+                    Courier::ElementalNodeNonChannel::UnionMember0,
+                    Courier::ElementalNodeNonChannel::UnionMember1,
+                    Courier::ElementalNodeNonChannel::UnionMember2,
+                    Courier::ElementalNodeNonChannel::UnionMember3,
+                    Courier::ElementalNodeNonChannel::UnionMember4,
+                    Courier::ElementalNodeNonChannel::UnionMember5,
+                    Courier::ElementalNodeNonChannel::UnionMember6
+                  )
+                ]
+              ),
             font_size: T.nilable(String),
             line_height: T.nilable(String),
             padding: T.nilable(String),