broadcast-ruby 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06eed741f3800e40f0734e35389d38fe527b22508b4bd623621a7eb54bb0ed3e
-  data.tar.gz: 8dd349d9829003e8895f1d2612d5c86cd5248037307a32313a4e6b05f943a1d1
+  metadata.gz: 6691d4bb7e0fb74c2f3fe326d1ef2ae6797ec957f730be3d62287c07b13b2b65
+  data.tar.gz: 6117bc0c528ddb576ec51eafe1c56071b05fc354d06cbe66b067effbe2f8e560
 SHA512:
-  metadata.gz: 425b9de89f5fc7448483c66e082a42ef1a0b81dc13e7e8ec0067d5c43cf02da3197f7c80826b1b896ea59fe79abe631fd37b2b38e7180fa4f37320e58698d91d
-  data.tar.gz: f3d825c247f222b67e8d76e63a9fbaf14cab5a6a1ad81768ec22a9712c0a56de8ca10733b99a5e26755ae20618fe25228465935129e33a7d4254312ee6b8c01d
+  metadata.gz: 86f1f4579ff54f8677f1848efa21d097bea66ab5e2102fcc05763021a4f7ff05b34818b93e506631f2cd241bbe87c21d587bc0f6ff60f72adadad4f3acefc009
+  data.tar.gz: b0a6d3889b396bce312a174f3da12e87a3f20ac729c91c26891a03f1b6f7f1f696f02d1c5681773b1f3fdc649034426d52a637891fe3153b8e0d0e4b044fc6a1

data/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 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
+
+- `Migration#unsubscribed_emails` for `GET /api/migration/v1/unsubscribed_emails`,
+  the channel's own suppression list (rows `id`, `email`,
+  `broadcast_channel_id`, `created_at`, `updated_at`). `each_record(:unsubscribed_emails)`
+  pages it. `suppressions` returns only the global suppression list, so an
+  export needs both.
+
 ## [0.5.0] - 2026-09-25
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    broadcast-ruby (0.5.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.5.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, ...
@@ -1380,10 +1412,14 @@ Available collections:
 ```
 channels  subscribers  templates  segments  sequences  email_servers
 opt_in_forms  broadcasts  outbound_receipts  webhook_endpoints  tokens
-suppressions  tags  users  link_redirects  link_clicks
-subscriber_histories  file_assets
+suppressions  unsubscribed_emails  tags  users  link_redirects
+link_clicks  subscriber_histories  file_assets
 ```
 
+`suppressions` is the global suppression list (GlobalSuppression rows, global
+or scoped to the channel). `unsubscribed_emails` is the channel's own
+suppression list. Export both to keep every suppressed address.
+
 File assets are downloaded separately and return raw bytes:
 
 ```ruby

data/SDK-COVERAGE.md

@@ -53,7 +53,7 @@ Two details worth knowing when reading the map below:
 - **PATCH is canonical.** Rails' `resources` routes `update` to both PATCH and
   PUT. They are one operation; the generator drops the PUT alias. Counting both
   would inflate the denominator by 8 and make this gem look 8 endpoints short.
-- **Metaprogrammed endpoints are declared.** The 18 migration collections are
+- **Metaprogrammed endpoints are declared.** The 19 migration collections are
   defined by `define_method` over `Migration::COLLECTIONS`, so no path literal
   exists to scan. They are listed in `.api-coverage.yml` and marked
   *(generated)* below. That file is produced from the gem's own constants — it
@@ -268,6 +268,7 @@ on the client and the gem attaches it.
 | GET | `/api/migration/v1/webhook_endpoints` | *(generated)* `Migration#webhook_endpoints` |
 | GET | `/api/migration/v1/tokens` | *(generated)* `Migration#tokens` |
 | GET | `/api/migration/v1/suppressions` | *(generated)* `Migration#suppressions` |
+| GET | `/api/migration/v1/unsubscribed_emails` | *(generated)* `Migration#unsubscribed_emails` |
 | GET | `/api/migration/v1/tags` | *(generated)* `Migration#tags` |
 | GET | `/api/migration/v1/users` | *(generated)* `Migration#users` |
 | GET | `/api/migration/v1/link_redirects` | *(generated)* `Migration#link_redirects` |
@@ -330,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/migration.rb

@@ -20,8 +20,8 @@ module Broadcast
       COLLECTIONS = %i[
         channels subscribers templates segments sequences email_servers
         opt_in_forms broadcasts outbound_receipts webhook_endpoints tokens
-        suppressions tags users link_redirects link_clicks subscriber_histories
-        file_assets
+        suppressions unsubscribed_emails tags users link_redirects link_clicks
+        subscriber_histories file_assets
       ].freeze
 
       COLLECTIONS.each do |collection|

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.5.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.5.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