broadcast-ruby 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98cb127e971456521ce14ecd8b2f3f8a90b5ce295623c6ad3e8b60495f3b231f
-  data.tar.gz: ac3dab036f2d6bfdf07108e82e14c57821010ecbbc0434355b85319f71c63868
+  metadata.gz: 722b6b8aba5a3d87fbdacbab42f757071d0f4b7bc548a803f9b28fb0b4596ec9
+  data.tar.gz: 78c247ac8e18e66f3fff0e380b8a0d299047d15994765a0ad6ddb8f13cb766ba
 SHA512:
-  metadata.gz: 901e3de9e03327d7750e80b55ef9db13dd615eb258ddef2ec36d0c6063d7b3307689798b626a05fcc6c38e611a0954977f2341de0584f89be103d2e16bfae2e2
-  data.tar.gz: b657ab5a20df302fc9e0c5b217937deb50ddec49dc4f87200f95292433e4464eb0c89ae7104b741f787909d2a9b1b5d5f9117e1a2730c3d2c0e3c29cf502e849
+  metadata.gz: a3cd09cc4c96d57ed30c64c8c48fade4f75bb6f5c15136819f7725e9eea1f8811b8e3bd91ec70125d92ad8411fcf60ca04cc0b5461bd50858e5f6c611f2246fe
+  data.tar.gz: edf1130a392a68a08fc95c1a29619e1a0399dbe0373c85048b6c45bba12a8dff88fb9ed84b1364c06ba5b5c9fa2c90e5da8fd083bd99b7d832a122cb72d3501e

data/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-10
+
+### Added
+
+- `email.send_delayed` and `broadcast.batch_completed` in
+  `Broadcast::Webhook::EVENT_TYPES` (and in `EMAIL_EVENTS` /
+  `BROADCAST_EVENTS`), matching the server (Broadcast 2.43.0).
+  `email.send_delayed` fires when a transactional email waits for room under
+  its server's hourly limit.
+- `excluded_segment_ids` on broadcasts, sequences and autopilots (create,
+  update, and in the returned record): segments a send never reaches. The
+  server refuses a segment that is both sent to and excluded with 422.
+- `subscribers.create(unsubscribed_at: ...)`: creates a subscriber who has
+  already unsubscribed, in one request, with any token. Before, the server
+  ignored the field and a migration had to create, then unsubscribe.
+
+- `Broadcast::Resources::OptInForms::TRIGGER_FREQUENCIES`: the words
+  `trigger_settings[:frequency]` accepts (`always`, `every_visit`,
+  `once_per_session`, `once_per_day`, `once_per_week`, `once`).
+
+### Changed
+
+- Opt-in forms: the server now refuses an unknown `trigger_settings`
+  frequency word with 422 (`Broadcast::ValidationError`). Before, it saved
+  any word, and an unknown one showed the popup on every visit. The client
+  still sends what it is given.
+
+## [0.7.0] - 2026-10-06
+
+### Added
+
+- `Topics` resource (`client.topics`): `list`, `get_topic`, `create`, `update`,
+  `delete` for `/api/v1/topics` (subscriber topics; uses the subscriber
+  permissions). Broadcasts and sequences accept `topic_id`.
+- `Subscribers#update` takes `custom_data_mode:` (`'replace'` default, or
+  `'merge'`: change only the keys sent, `nil` deletes a key).
+- `subscriber.preferences_updated` webhook event type, in
+  `Broadcast::Webhook::SUBSCRIBER_EVENTS` and `EVENT_TYPES` (now 35).
+
 ## [0.6.0] - 2026-10-03
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    broadcast-ruby (0.6.0)
+    broadcast-ruby (0.8.0)
       base64
 
 GEM
@@ -177,7 +177,7 @@ CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
-  broadcast-ruby (0.6.0)
+  broadcast-ruby (0.8.0)
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a

data/README.md

@@ -712,6 +712,44 @@ client.broadcasts.statistics_links(1, sort: 'clicks', order: 'desc')
 
 ---
 
+## Topics
+
+A topic is one kind of email subscribers opt in to or out of (webinars, offers).
+Its value lives in a top-level `custom_data` key (`true`, `false`, or no value)
+or in a tag. `unset_receives` decides, at send time, whether a subscriber with no
+value receives it; Broadcast never writes a default. A broadcast or sequence with
+a `topic_id` reaches only the topic's receivers: (segments) AND topic.
+
+**Required permissions:** `subscribers_read`, `subscribers_write`
+
+```ruby
+client.topics.list['data']  # => [{'id' => 1, 'name' => 'Webinars', 'custom_data_key' => 'sub_webinars', ...}]
+client.topics.get_topic(1)
+
+topic = client.topics.create(name: 'Webinars', custom_data_key: 'sub_webinars')
+client.topics.create(name: 'News', storage: 'tag', tag_name: 'news')
+client.topics.update(topic['id'], unset_receives: false)
+client.topics.delete(topic['id'])  # 422 while a broadcast or sequence uses it
+
+# Send to a topic
+client.broadcasts.create(subject: 'Webinar', body: '...', segment_ids: [2], topic_id: topic['id'])
+
+# Send to everyone except a segment (also on sequences and autopilots)
+client.broadcasts.create(subject: 'Offer', body: '...', excluded_segment_ids: [competitors['id']])
+
+# Migrate someone who already unsubscribed, in one request
+client.subscribers.create(email: 'opted-out@example.com', unsubscribed_at: '2025-03-14T09:30:00Z')
+
+# Change only the keys you send (nil deletes a key); the default replaces custom_data
+client.subscribers.update('jane@example.com', custom_data: { sub_webinars: false }, custom_data_mode: 'merge')
+```
+
+The subscriber JSON has `topics`: each topic's stored value (`true`, `false`, or
+`nil`). Topic changes fire `subscriber.preferences_updated` (from/to per topic,
+`changed_at`, `change_source`) as well as `subscriber.updated`.
+
+---
+
 ## Segments
 
 Define subscriber groups using rules for targeted broadcasts and sequence enrollment.
@@ -857,6 +895,11 @@ result = client.opt_in_forms.create(
 # Update (deeply nested settings hashes pass through verbatim)
 client.opt_in_forms.update(1, enabled: false)
 
+# How often the same visitor sees a popup. Any word outside
+# Broadcast::Resources::OptInForms::TRIGGER_FREQUENCIES raises
+# Broadcast::ValidationError (422).
+client.opt_in_forms.update(1, trigger_settings: { frequency: 'once_per_day' })
+
 # Delete
 client.opt_in_forms.delete(1)
 ```
@@ -1131,7 +1174,7 @@ secret = result['secret']
 
 # Every valid event type is available as a constant. An unknown event type is
 # dropped server-side rather than rejected, so subscribe from these.
-Broadcast::Webhook::EVENT_TYPES        # all 34
+Broadcast::Webhook::EVENT_TYPES        # all 37
 Broadcast::Webhook::EMAIL_EVENTS       # email.sent, email.delivered, ...
 Broadcast::Webhook::SUBSCRIBER_EVENTS  # subscriber.created, ..., subscribers.purged
 Broadcast::Webhook::BROADCAST_EVENTS   # broadcast.sending, broadcast.sent, ...
@@ -1162,9 +1205,9 @@ result['data']  # => [{'id' => 1, 'event_type' => 'email.sent', 'response_status
 
 | Category | Events |
 |----------|--------|
-| Email | `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.opened`, `email.clicked`, `email.bounced`, `email.complained`, `email.failed` |
+| Email | `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.send_delayed`, `email.opened`, `email.clicked`, `email.bounced`, `email.complained`, `email.failed` |
 | Subscriber | `subscriber.created`, `subscriber.updated`, `subscriber.deleted`, `subscriber.subscribed`, `subscriber.unsubscribed`, `subscriber.bounced`, `subscriber.complained`, `subscribers.purged`, `subscribers.purge_failed` |
-| Broadcast | `broadcast.scheduled`, `broadcast.queueing`, `broadcast.sending`, `broadcast.sent`, `broadcast.failed`, `broadcast.partial_failure`, `broadcast.aborted`, `broadcast.paused` |
+| Broadcast | `broadcast.scheduled`, `broadcast.queueing`, `broadcast.sending`, `broadcast.sent`, `broadcast.failed`, `broadcast.partial_failure`, `broadcast.aborted`, `broadcast.paused`, `broadcast.batch_completed` |
 | Sequence | `sequence.subscriber_added`, `sequence.subscriber_completed`, `sequence.subscriber_moved`, `sequence.subscriber_removed`, `sequence.subscriber_paused`, `sequence.subscriber_resumed`, `sequence.subscriber_error` |
 | System | `message.attempt.exhausted`, `test.webhook` |
 

data/SDK-COVERAGE.md

@@ -331,7 +331,7 @@ Inbound webhooks — the app calling you.
 | HMAC-SHA256 verification (`v1,<base64>`) | ✅ `Webhook.verify` |
 | 5-minute timestamp tolerance | ✅ Replay protection |
 | Constant-time comparison | ✅ `OpenSSL.fixed_length_secure_compare` |
-| Event type constants | ✅ `Webhook::EVENT_TYPES` — 34 values |
+| Event type constants | ✅ `Webhook::EVENT_TYPES` — 37 values |
 
 Categories: `EMAIL_EVENTS` (8), `SUBSCRIBER_EVENTS` (7), `BROADCAST_EVENTS` (8),
 `SEQUENCE_EVENTS` (7), `SYSTEM_EVENTS` (2).

data/lib/broadcast/client.rb

@@ -99,6 +99,10 @@ module Broadcast
       @segments ||= Resources::Segments.new(self)
     end
 
+    def topics
+      @topics ||= Resources::Topics.new(self)
+    end
+
     def templates
       @templates ||= Resources::Templates.new(self)
     end

data/lib/broadcast/resources/autopilots.rb

@@ -30,6 +30,7 @@ module Broadcast
       #   copies_to_generate:    how many drafts each run produces
       #   tone_description:, content_instructions:, newsletter_structure:
       #   segment_ids:           array — restrict the newsletter's audience
+      #   excluded_segment_ids:  array — segments its drafts never reach
       def create(**attrs)
         post('/api/v1/autopilots', { autopilot: attrs })
       end

data/lib/broadcast/resources/opt_in_forms.rb

@@ -5,6 +5,12 @@ require 'date'
 module Broadcast
   module Resources
     class OptInForms < Base
+      # The words trigger_settings[:frequency] accepts: how often the same visitor
+      # sees a popup. always and every_visit mean the same. The server refuses any
+      # other word with 422 (Broadcast::ValidationError); the client does not
+      # check, so an older server is never refused a word it would take.
+      TRIGGER_FREQUENCIES = %w[always every_visit once_per_session once_per_day once_per_week once].freeze
+
       # List opt-in forms.
       #
       # NOTE: returns up to 250 results per page along with `pagination`
@@ -36,6 +42,10 @@ module Broadcast
       #
       # Custom fields declared in opt_in_form_blocks_attributes support a
       # multi-line variant, which renders as a textarea on the hosted form.
+      #
+      # trigger_settings: { frequency: } must be one of TRIGGER_FREQUENCIES;
+      # any other word raises Broadcast::ValidationError (422). Keys sent in a
+      # settings hash are merged into the stored settings.
       def create(**attrs)
         post('/api/v1/opt_in_forms', { opt_in_form: attrs })
       end

data/lib/broadcast/resources/subscribers.rb

@@ -45,7 +45,13 @@ module Broadcast
       #                                another provider. Ignored (with a warning) on update,
       #                                and ignored entirely for channel-scoped tokens.
       #
-      # Note `unsubscribed_at` is never settable here — use `unsubscribe(email)`.
+      # Any token, create only:
+      #   unsubscribed_at:             ISO 8601. Stores the subscriber as unsubscribed in the
+      #                                same request (inactive, on the unsubscribe list), for
+      #                                migrating a list with its opt-outs intact. No
+      #                                confirmation email; 422 if it is in the future or sent
+      #                                with is_active: true. To unsubscribe an existing
+      #                                subscriber, use `unsubscribe(email)`.
       def create(**attrs)
         double_opt_in = attrs.delete(:double_opt_in)
         confirmation_template_id = attrs.delete(:confirmation_template_id)
@@ -57,8 +63,12 @@ module Broadcast
         post('/api/v1/subscribers.json', payload)
       end
 
-      def update(email, **attrs)
-        patch('/api/v1/subscribers.json', { email: email, subscriber: attrs })
+      # custom_data_mode: 'replace' (the API default) stores custom_data as sent;
+      # 'merge' changes only the keys sent, and a nil value deletes that key.
+      def update(email, custom_data_mode: nil, **attrs)
+        body = { email: email, subscriber: attrs }
+        body[:custom_data_mode] = custom_data_mode if custom_data_mode
+        patch('/api/v1/subscribers.json', body)
       end
 
       def add_tags(email, tags)

data/lib/broadcast/resources/topics.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # Subscriber topics: kinds of email subscribers opt in to or out of. A topic
+    # reads a top-level custom_data key (true, false, or no value) or a tag.
+    # Uses the token's subscriber permissions.
+    class Topics < Base
+      def list(**params)
+        get('/api/v1/topics.json', params)
+      end
+
+      def get_topic(id)
+        get("/api/v1/topics/#{id}.json")
+      end
+
+      def create(**attrs)
+        post('/api/v1/topics', { topic: attrs })
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/topics/#{id}", { topic: attrs })
+      end
+
+      # Refused (422) while a broadcast or sequence uses the topic.
+      def delete(id)
+        @client.request(:delete, "/api/v1/topics/#{id}")
+      end
+    end
+  end
+end

data/lib/broadcast/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Broadcast
-  VERSION = '0.6.0'
+  VERSION = '0.8.0'
 end

data/lib/broadcast/webhook.rb

@@ -10,15 +10,18 @@ module Broadcast
     # Every event type a webhook endpoint can subscribe to, mirroring
     # WebhookEndpoint::AVAILABLE_EVENT_TYPES server-side. Use these when
     # creating an endpoint — an unknown event type is dropped silently.
+    # email.send_delayed: a transactional email is waiting for room under its
+    # server's hourly limit (not yet sent). email.delivery_delayed: the
+    # provider accepted it and the recipient's server is delaying it.
     EMAIL_EVENTS = %w[
-      email.sent email.delivered email.delivery_delayed email.complained
-      email.bounced email.opened email.clicked email.failed
+      email.sent email.delivered email.delivery_delayed email.send_delayed
+      email.complained email.bounced email.opened email.clicked email.failed
     ].freeze
 
     # subscribers.* are sent once for a whole-list purge, in place of a
     # subscriber.deleted per row.
     SUBSCRIBER_EVENTS = %w[
-      subscriber.created subscriber.updated subscriber.deleted
+      subscriber.created subscriber.updated subscriber.preferences_updated subscriber.deleted
       subscriber.subscribed subscriber.unsubscribed subscriber.bounced
       subscriber.complained subscribers.purged subscribers.purge_failed
     ].freeze
@@ -26,7 +29,7 @@ module Broadcast
     BROADCAST_EVENTS = %w[
       broadcast.scheduled broadcast.queueing broadcast.sending broadcast.sent
       broadcast.failed broadcast.partial_failure broadcast.aborted
-      broadcast.paused
+      broadcast.paused broadcast.batch_completed
     ].freeze
 
     SEQUENCE_EVENTS = %w[

data/lib/broadcast.rb

@@ -13,6 +13,7 @@ require_relative 'broadcast/resources/subscribers'
 require_relative 'broadcast/resources/sequences'
 require_relative 'broadcast/resources/broadcasts'
 require_relative 'broadcast/resources/segments'
+require_relative 'broadcast/resources/topics'
 require_relative 'broadcast/resources/templates'
 require_relative 'broadcast/resources/webhook_endpoints'
 require_relative 'broadcast/resources/transactionals'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Simon Chiu
@@ -61,6 +61,7 @@ files:
 - lib/broadcast/resources/subscribers.rb
 - lib/broadcast/resources/suppressions.rb
 - lib/broadcast/resources/templates.rb
+- lib/broadcast/resources/topics.rb
 - lib/broadcast/resources/transactionals.rb
 - lib/broadcast/resources/users.rb
 - lib/broadcast/resources/webhook_endpoints.rb
@@ -90,7 +91,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby client for the Broadcast email platform
 test_files: []