broadcast-ruby 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98cb127e971456521ce14ecd8b2f3f8a90b5ce295623c6ad3e8b60495f3b231f
-  data.tar.gz: ac3dab036f2d6bfdf07108e82e14c57821010ecbbc0434355b85319f71c63868
+  metadata.gz: 6691d4bb7e0fb74c2f3fe326d1ef2ae6797ec957f730be3d62287c07b13b2b65
+  data.tar.gz: 6117bc0c528ddb576ec51eafe1c56071b05fc354d06cbe66b067effbe2f8e560
 SHA512:
-  metadata.gz: 901e3de9e03327d7750e80b55ef9db13dd615eb258ddef2ec36d0c6063d7b3307689798b626a05fcc6c38e611a0954977f2341de0584f89be103d2e16bfae2e2
-  data.tar.gz: b657ab5a20df302fc9e0c5b217937deb50ddec49dc4f87200f95292433e4464eb0c89ae7104b741f787909d2a9b1b5d5f9117e1a2730c3d2c0e3c29cf502e849
+  metadata.gz: 86f1f4579ff54f8677f1848efa21d097bea66ab5e2102fcc05763021a4f7ff05b34818b93e506631f2cd241bbe87c21d587bc0f6ff60f72adadad4f3acefc009
+  data.tar.gz: b0a6d3889b396bce312a174f3da12e87a3f20ac729c91c26891a03f1b6f7f1f696f02d1c5681773b1f3fdc649034426d52a637891fe3153b8e0d0e4b044fc6a1

data/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [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.7.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.7.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,38 @@ 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'])
+
+# 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.
@@ -1131,7 +1163,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 35
 Broadcast::Webhook::EMAIL_EVENTS       # email.sent, email.delivered, ...
 Broadcast::Webhook::SUBSCRIBER_EVENTS  # subscriber.created, ..., subscribers.purged
 Broadcast::Webhook::BROADCAST_EVENTS   # broadcast.sending, broadcast.sent, ...

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` — 35 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/subscribers.rb

@@ -57,8 +57,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.7.0'
 end

data/lib/broadcast/webhook.rb

@@ -18,7 +18,7 @@ module Broadcast
     # 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

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.7.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: []