broadcast-ruby 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6691d4bb7e0fb74c2f3fe326d1ef2ae6797ec957f730be3d62287c07b13b2b65
-  data.tar.gz: 6117bc0c528ddb576ec51eafe1c56071b05fc354d06cbe66b067effbe2f8e560
+  metadata.gz: 46cb94477a871cda3ac8f5a69d2d947b2ec87b5dd4454a1ec8d179cec7f25b9a
+  data.tar.gz: 38f72f3aecd7376ed6f072e831049614ae5f329c8e92cb0e1aeb3d26648f8829
 SHA512:
-  metadata.gz: 86f1f4579ff54f8677f1848efa21d097bea66ab5e2102fcc05763021a4f7ff05b34818b93e506631f2cd241bbe87c21d587bc0f6ff60f72adadad4f3acefc009
-  data.tar.gz: b0a6d3889b396bce312a174f3da12e87a3f20ac729c91c26891a03f1b6f7f1f696f02d1c5681773b1f3fdc649034426d52a637891fe3153b8e0d0e4b044fc6a1
+  metadata.gz: e46bf11d5142f63a5bde2fc5d6d0c34c5d352fc05e428e1c3bc05931e346c9cff163f664d611f2ea88c1d5af819ed9d09b2fde518d5fe4fd6629ab650626bb4f
+  data.tar.gz: ca25863674f4560506aca95d62739ca8998a0671cfc52561b99b1dac26f6c519d6ff19c1781b121a4f3b72d6902b5e00360f30418d954aac3a34ad3fbbe83515

data/CHANGELOG.md

@@ -4,6 +4,54 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-10-16
+
+### Added
+
+- `file_assets` for the File Assets API (Broadcast 2.48.0): `list(filter:,
+  limit:, offset:)`, `get_file_asset(id)`, `upload(path_or_io, filename:,
+  content_type:, channel_restricted:, idempotency_key:)` (multipart),
+  `upload_base64(filename:, data:, ...)` (JSON) and `delete(id)`. The returned
+  `url` is what `channel.update_design(brand: { logo_url: })` takes. Needs the
+  new `file_assets` permissions.
+- Multipart request support in the HTTP layer (`Broadcast::FilePart`). The
+  debug log shows a file part as its name and size, and cuts strings over
+  1,000 characters short, so an upload never writes the file into the log.
+- `channel.settings` and `channel.update_settings(**groups)` for
+  `GET`/`PATCH /api/v1/channel/settings` (Broadcast 2.46.0): general, sender,
+  unsubscribe page (with the privacy policy and legal notice links),
+  confirmation page and opt-in forms (`opt_in_forms.match_brand_kit`) settings. Needs the new `channel_settings` permissions.
+- `channel.update_design(**kit)` for `PATCH /api/v1/channel/design`
+  (Broadcast 2.46.0): change the brand kit. Needs `channel_settings_write`.
+  The logo is the `logo_url` of an image in the channel's file library.
+
+## [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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    broadcast-ruby (0.7.0)
+    broadcast-ruby (0.9.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.7.0)
+  broadcast-ruby (0.9.0)
   builder (3.3.0) sha256=497918d2f9dca528fdca4b88d84e4ef4387256d984b8154e9d5d3fe5a9c8835f
   concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a

data/README.md

@@ -734,6 +734,12 @@ 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')
 ```
@@ -833,9 +839,10 @@ client.templates.delete(1)
 
 ### Brand Kit
 
-Read the channel's brand kit (Settings → Design) so your own templates can
-match it. Read-only, fully resolved (defaults filled in), and always the
-token's own channel, so it takes no arguments. Needs `templates_read`.
+Read the channel's brand kit (Settings → Brand Kit) so your own templates can
+match it. Fully resolved (defaults filled in), and always the token's own
+channel, so it takes no arguments. Needs `templates_read` (or, from Broadcast
+2.46.0, `channel_settings_read`).
 
 ```ruby
 design = client.channel.design
@@ -848,8 +855,93 @@ design['brand']['website_url']       # => 'https://acme.example'
 design['brand']['social_links']      # => [{ 'network' => 'x', 'url' => 'https://x.com/acme' }]
 ```
 
+Change it with `update_design` (Broadcast 2.46.0 or later, needs
+`channel_settings_write`). Send only what changes, in the same shape. An
+empty string or `nil` puts a value back to its default, and `social_links`
+replaces the list. `font_stack` and `width` are read-only. The logo is the
+`logo_url` of an image in the channel's file library; the server never
+fetches a URL.
+
+```ruby
+kit = client.channel.update_design(
+  colors: { accent: '#ff5500' },
+  typography: { font: 'georgia' },
+  brand: { logo_url: 'https://your-broadcast.example/files/eyJ...-logo.png', logo_width: 200 }
+)
+kit['colors']['accent']   # => '#ff5500' (the whole kit comes back)
+kit.warnings              # => e.g. an unrecognized key you sent
+```
+
+An unknown font, icon style or social network, a logo from outside the file
+library, or a value the Brand Kit page would refuse raises
+`Broadcast::ValidationError` (422), and nothing is saved.
+
+### Channel Settings
+
+Read and change the channel's settings (Broadcast 2.46.0 or later), grouped
+like the Settings pages: `general`, `sender`, `unsubscribe_page` (including
+the privacy policy and legal notice links), `confirmation_page` and
+`opt_in_forms` (`match_brand_kit`: whether new opt-in forms start from the
+brand kit). Needs `channel_settings_read` to read and `channel_settings_write`
+to change; both are off on every token until you tick them.
+
+The `match_brand_kit` switches (`unsubscribe_page`, `confirmation_page`
+and `opt_in_forms`) decide where the brand kit is used. They are set
+here, not with the brand kit update.
+
+```ruby
+settings = client.channel.settings
+settings['unsubscribe_page']['legal_notice_url']   # => 'https://example.com/impressum'
+
+result = client.channel.update_settings(
+  unsubscribe_page: {
+    privacy_policy_url: 'https://example.com/privacy',
+    legal_notice_url: 'https://example.com/impressum'
+  }
+)
+result.warnings   # => e.g. [#<Warning code="unrecognized_parameter" param="channel_settings.general.domain" ...>]
+```
+
+Updates are partial: nested text and colours merge, an empty string or `nil`
+removes a value, and `languages` replaces the list. A value outside a fixed
+set, or one that fails validation, raises `Broadcast::ValidationError` and
+saves nothing.
+
 ---
 
+## File Assets
+
+The channel's file library (Broadcast 2.48.0 or later): PNG, JPEG and GIF
+images under 10 MB, each with a public URL that never expires. Use the URL in
+emails, or as the brand kit logo. Needs `file_assets_read` to list and get,
+and `file_assets_write` to upload and delete.
+
+```ruby
+# Upload from a path (multipart). The content type follows the extension.
+file = client.file_assets.upload('logo.png')
+file['url']   # => 'https://your-broadcast.example/files/eyJ...-logo.png'
+
+# From an IO, with a filename; link it to this channel only; safe to retry
+client.file_assets.upload(io, filename: 'banner.gif', channel_restricted: true,
+                              idempotency_key: "banner-#{campaign.id}")
+
+# Already have base64? Send it as JSON.
+client.file_assets.upload_base64(filename: 'logo.png', content_type: 'image/png',
+                                 data: Base64.strict_encode64(bytes))
+
+# Use it as the brand kit logo
+client.channel.update_design(brand: { logo_url: file['url'] })
+
+client.file_assets.list(filter: 'logo', limit: 20)   # => { 'data' => [...], 'total' => n }
+client.file_assets.get_file_asset(file['id'])
+client.file_assets.delete(file['id'])
+```
+
+A file that is not a PNG, JPEG or GIF, a file of 10 MB or more, or invalid
+base64 raises `Broadcast::ValidationError` (422). So does deleting a file
+that is a channel's brand kit logo: set another logo first. The server never
+fetches a URL; upload the bytes.
+
 ## Opt-In Forms
 
 Embeddable subscription forms with theming, A/B variants, and analytics.
@@ -889,6 +981,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)
 ```
@@ -1163,7 +1260,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 35
+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, ...
@@ -1194,9 +1291,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` |
 
@@ -1477,7 +1574,9 @@ Each token can be scoped to specific resources. The ActionMailer delivery method
 | Users (admin token only) | `users_read` -- list, get, channel_permissions, system_permissions | `users_write` -- create, update, deactivate, activate, delete, permission writes |
 | Webhook Endpoints | `webhook_endpoints_read` -- list, get, deliveries | `webhook_endpoints_write` -- create, update, delete, test |
 | Autopilot | `autopilot_read` -- list, get, runs | `autopilot_write` -- create, update, delete, activate, pause, deactivate, trigger_run |
+| Channel Settings | `channel_settings_read` -- `channel.settings`, `channel.design` | `channel_settings_write` -- `channel.update_settings`, `channel.update_design` |
 | Suppressions | `suppressions_read` -- list, check | `suppressions_write` -- add, remove, bulk add/remove |
+| File Assets | `file_assets_read` -- list, get | `file_assets_write` -- upload, upload_base64, delete |
 
 ---
 

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` — 35 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

@@ -153,6 +153,11 @@ module Broadcast
       @channel ||= Resources::Channel.new(self)
     end
 
+    # The channel's file library: upload images and get their public URLs.
+    def file_assets
+      @file_assets ||= Resources::FileAssets.new(self)
+    end
+
     # Read-only export endpoints under /api/migration/v1. Requires an admin
     # (system) API token.
     def migration
@@ -160,9 +165,11 @@ module Broadcast
     end
 
     # @api private
-    def request(method, path, body_or_params = nil, headers: {}, raw: false)
+    # rubocop:disable Metrics/ParameterLists -- transport options passed straight through to Connection
+    def request(method, path, body_or_params = nil, headers: {}, raw: false, multipart: false)
+      # rubocop:enable Metrics/ParameterLists
       payload = inject_channel_scope(body_or_params)
-      @connection.request(method, path, payload, headers: headers, raw: raw)
+      @connection.request(method, path, payload, headers: headers, raw: raw, multipart: multipart)
     end
 
     private

data/lib/broadcast/connection.rb

@@ -28,9 +28,13 @@ module Broadcast
 
     # @param raw [Boolean] return the response body as a String instead of
     #   parsing it as JSON — for text/plain endpoints such as /api/v1/skill.
-    def request(method, path, payload = nil, headers: {}, raw: false)
+    # @param multipart [Boolean] send the payload as multipart/form-data
+    #   (Broadcast::FilePart values become file parts) instead of JSON.
+    # rubocop:disable Metrics/ParameterLists -- one keyword per transport option
+    def request(method, path, payload = nil, headers: {}, raw: false, multipart: false)
+      # rubocop:enable Metrics/ParameterLists
       uri = build_uri(path, method, payload)
-      context = { headers: headers, raw: raw, redirects: 0 }
+      context = { headers: headers, raw: raw, redirects: 0, multipart: multipart }
 
       retry_with_backoff { execute(method, uri, payload, context) }
     rescue Net::OpenTimeout, Net::ReadTimeout => e
@@ -52,7 +56,11 @@ module Broadcast
       http.read_timeout = @config.timeout
 
       req = build_request(method, uri, context[:headers])
-      req.body = payload.to_json if method != :get && payload_present?(payload)
+      if context[:multipart]
+        req.body, req['Content-Type'] = Multipart.build(payload || {})
+      elsif method != :get && payload_present?(payload)
+        req.body = payload.to_json
+      end
 
       @debug_logger.request(req, method == :get ? nil : payload)
       response = http.request(req)

data/lib/broadcast/debug_logger.rb

@@ -17,6 +17,9 @@ module Broadcast
       api_key api_token password secret
     ].freeze
 
+    # Longer strings are cut short in the log.
+    MAX_LOGGED_STRING = 1000
+
     def initialize(config)
       @config = config
     end
@@ -56,6 +59,12 @@ module Broadcast
         end
       when Array
         value.map { |item| redact(item) }
+      when FilePart
+        value.inspect
+      when String
+        # A base64 file upload (file_assets.upload_base64) would otherwise
+        # write megabytes into the log.
+        value.length > MAX_LOGGED_STRING ? "#{value[0, 40]}... (#{value.length} characters)" : value
       else
         value
       end

data/lib/broadcast/multipart.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Broadcast
+  # A file in a multipart/form-data request: the bytes, and the filename and
+  # content type sent with them. Holding the bytes (not an IO) keeps a retry
+  # safe: every attempt builds the body afresh.
+  FilePart = Struct.new(:bytes, :filename, :content_type) do
+    def inspect
+      "#<Broadcast::FilePart #{filename} (#{content_type}, #{bytes.bytesize} bytes)>"
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # Builds a multipart/form-data body by hand. Net::HTTP's set_form streams
+  # the body at send time, which the debug logger and test doubles cannot see.
+  module Multipart
+    module_function
+
+    # @param fields [Hash] values are FileParts or anything with #to_s; nil is left out
+    # @return [Array(String, String)] the body (binary) and the Content-Type header
+    def build(fields)
+      boundary = "BroadcastRuby#{SecureRandom.hex(16)}"
+      body = String.new(encoding: Encoding::BINARY)
+
+      fields.each do |name, value|
+        next if value.nil?
+
+        body << "--#{boundary}\r\n"
+        if value.is_a?(FilePart)
+          body << "Content-Disposition: form-data; name=\"#{quote(name)}\"; filename=\"#{quote(value.filename)}\"\r\n"
+          body << "Content-Type: #{value.content_type}\r\n\r\n"
+          body << value.bytes.b
+        else
+          body << "Content-Disposition: form-data; name=\"#{quote(name)}\"\r\n\r\n"
+          body << value.to_s.b
+        end
+        body << "\r\n"
+      end
+      body << "--#{boundary}--\r\n"
+
+      [body, "multipart/form-data; boundary=#{boundary}"]
+    end
+
+    # A quote or a line break in a name would end the header early.
+    def quote(value)
+      value.to_s.gsub(/[\r\n]/, ' ').gsub('"', '%22').b
+    end
+  end
+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/channel.rb

@@ -6,9 +6,9 @@ module Broadcast
     # (or, for an admin token, the channel it is scoped to); there is no
     # channel id argument.
     class Channel < Base
-      # The channel's brand kit from Settings -> Design, fully resolved
-      # (defaults filled in), read-only. Requires the `templates_read`
-      # permission.
+      # The channel's brand kit from Settings -> Brand Kit, fully resolved
+      # (defaults filled in). Requires the `templates_read` permission (or,
+      # from Broadcast 2.46.0, `channel_settings_read`).
       #
       # Returns a Hash with `colors`, `typography` (`font` key and email-safe
       # `font_stack`), `layout` (`width`, `radius`), and `brand` (`logo_url` as
@@ -17,6 +17,42 @@ module Broadcast
       def design
         get('/api/v1/channel/design')
       end
+
+      # Changes the brand kit (Broadcast 2.46.0 or later). Requires the
+      # `channel_settings_write` permission.
+      #
+      # Partial: send only what changes, in the shape #design returns. An empty
+      # string or nil puts a value back to its default; `social_links`
+      # replaces the list. Set the logo with the `logo_url` of an image in the
+      # channel's file library. Returns the whole kit after the change, with
+      # any `warnings`.
+      #
+      #   client.channel.update_design(colors: { accent: '#ff5500' }, brand: { logo_url: nil })
+      def update_design(**design)
+        patch('/api/v1/channel/design', { channel_design: design })
+      end
+
+      # The channel's settings (Broadcast 2.46.0 or later), grouped like the
+      # Settings pages: `general`, `sender`, `unsubscribe_page` (with the legal
+      # links), `confirmation_page` and `opt_in_forms` (`match_brand_kit`, whether
+      # new opt-in forms start from the brand kit). The brand kit switches are
+      # set here, not with #update_design. Requires `channel_settings_read`.
+      def settings
+        get('/api/v1/channel/settings')
+      end
+
+      # Changes channel settings (Broadcast 2.46.0 or later). Requires
+      # `channel_settings_write`.
+      #
+      # Partial: send only the groups and keys that change. Nested text and
+      # colours merge, an empty string or nil removes a value, and
+      # `languages` replaces the list. Returns every setting after the
+      # change, with any `warnings`.
+      #
+      #   client.channel.update_settings(unsubscribe_page: { legal_notice_url: 'https://example.com/impressum' })
+      def update_settings(**settings)
+        patch('/api/v1/channel/settings', { channel_settings: settings })
+      end
     end
   end
 end

data/lib/broadcast/resources/file_assets.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # The channel's file library (Broadcast 2.48.0 or later): images (PNG,
+    # JPEG, GIF, under 10 MB) with public URLs that never expire. Use a file's
+    # `url` in emails, or as the brand kit logo:
+    #
+    #   file = client.file_assets.upload('logo.png')
+    #   client.channel.update_design(brand: { logo_url: file['url'] })
+    #
+    # Requires the `file_assets_read` permission to read and
+    # `file_assets_write` to upload and delete.
+    class FileAssets < Base
+      MAX_IDEMPOTENCY_KEY_LENGTH = 255
+
+      CONTENT_TYPES = {
+        '.png' => 'image/png',
+        '.jpg' => 'image/jpeg',
+        '.jpeg' => 'image/jpeg',
+        '.gif' => 'image/gif'
+      }.freeze
+
+      # Files the channel can see, newest first.
+      #
+      #   filter:  find files by file name (closest matches first)
+      #   limit:, offset:
+      #
+      # Returns `{ 'data' => [...], 'total' => n }`.
+      def list(**params)
+        get('/api/v1/file_assets', params)
+      end
+
+      def get_file_asset(id)
+        get("/api/v1/file_assets/#{id}")
+      end
+
+      # Uploads a file as multipart/form-data.
+      #
+      # `file` is a path, or an IO (then `filename:` is required). The content
+      # type follows the file extension unless `content_type:` is given.
+      #
+      #   channel_restricted: true links the file to this channel only
+      #                       (default: every channel, as in the web app)
+      #   idempotency_key:    makes a retry safe; see Transactionals#create
+      def upload(file, filename: nil, content_type: nil, channel_restricted: nil, idempotency_key: nil)
+        bytes, name = read_file(file, filename)
+        part = FilePart.new(bytes: bytes, filename: name, content_type: content_type || content_type_for(name))
+
+        fields = { file: part }
+        fields[:channel_restricted] = channel_restricted unless channel_restricted.nil?
+
+        @client.request(:post, '/api/v1/file_assets', fields,
+                        headers: idempotency_headers(idempotency_key), multipart: true)
+      end
+
+      # Uploads base64-encoded bytes in a JSON body, for callers that already
+      # hold base64 (or cannot send multipart).
+      def upload_base64(filename:, data:, content_type: nil, channel_restricted: nil, idempotency_key: nil)
+        payload = { filename: filename, data: data }
+        payload[:content_type] = content_type unless content_type.nil?
+        payload[:channel_restricted] = channel_restricted unless channel_restricted.nil?
+
+        @client.request(:post, '/api/v1/file_assets', payload, headers: idempotency_headers(idempotency_key))
+      end
+
+      # Deletes a file. A file that is a channel's brand kit logo is refused
+      # with Broadcast::ValidationError (422): choose another logo first.
+      def delete(id)
+        @client.request(:delete, "/api/v1/file_assets/#{id}")
+      end
+
+      private
+
+      def read_file(file, filename)
+        if file.respond_to?(:read)
+          if filename.nil? && !file.respond_to?(:path)
+            raise ArgumentError, 'filename: is required when uploading from an IO'
+          end
+
+          [file.read, filename || File.basename(file.path)]
+        else
+          path = file.to_s
+          [File.binread(path), filename || File.basename(path)]
+        end
+      end
+
+      def content_type_for(name)
+        CONTENT_TYPES.fetch(File.extname(name.to_s).downcase, 'application/octet-stream')
+      end
+
+      def idempotency_headers(key)
+        return {} if key.nil?
+
+        key = key.to_s.strip
+        return {} if key.empty?
+
+        if key.length > MAX_IDEMPOTENCY_KEY_LENGTH
+          raise ArgumentError,
+                "idempotency_key must be #{MAX_IDEMPOTENCY_KEY_LENGTH} characters or fewer (got #{key.length})"
+        end
+
+        { 'Idempotency-Key' => key }
+      end
+    end
+  end
+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)

data/lib/broadcast/version.rb

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

data/lib/broadcast/webhook.rb

@@ -10,9 +10,12 @@ 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
@@ -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

@@ -5,6 +5,7 @@ require_relative 'broadcast/errors'
 require_relative 'broadcast/response'
 require_relative 'broadcast/configuration'
 require_relative 'broadcast/debug_logger'
+require_relative 'broadcast/multipart'
 require_relative 'broadcast/connection'
 require_relative 'broadcast/client'
 require_relative 'broadcast/webhook'
@@ -25,6 +26,7 @@ require_relative 'broadcast/resources/discovery'
 require_relative 'broadcast/resources/suppressions'
 require_relative 'broadcast/resources/global_suppressions'
 require_relative 'broadcast/resources/channel'
+require_relative 'broadcast/resources/file_assets'
 require_relative 'broadcast/resources/migration'
 
 # ActionMailer integration — only loaded when Rails is present

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Simon Chiu
@@ -46,6 +46,7 @@ files:
 - lib/broadcast/debug_logger.rb
 - lib/broadcast/delivery_method.rb
 - lib/broadcast/errors.rb
+- lib/broadcast/multipart.rb
 - lib/broadcast/railtie.rb
 - lib/broadcast/resources/autopilots.rb
 - lib/broadcast/resources/base.rb
@@ -53,6 +54,7 @@ files:
 - lib/broadcast/resources/channel.rb
 - lib/broadcast/resources/discovery.rb
 - lib/broadcast/resources/email_servers.rb
+- lib/broadcast/resources/file_assets.rb
 - lib/broadcast/resources/global_suppressions.rb
 - lib/broadcast/resources/migration.rb
 - lib/broadcast/resources/opt_in_forms.rb