broadcast-ruby 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 722b6b8aba5a3d87fbdacbab42f757071d0f4b7bc548a803f9b28fb0b4596ec9
-  data.tar.gz: 78c247ac8e18e66f3fff0e380b8a0d299047d15994765a0ad6ddb8f13cb766ba
+  metadata.gz: 46cb94477a871cda3ac8f5a69d2d947b2ec87b5dd4454a1ec8d179cec7f25b9a
+  data.tar.gz: 38f72f3aecd7376ed6f072e831049614ae5f329c8e92cb0e1aeb3d26648f8829
 SHA512:
-  metadata.gz: a3cd09cc4c96d57ed30c64c8c48fade4f75bb6f5c15136819f7725e9eea1f8811b8e3bd91ec70125d92ad8411fcf60ca04cc0b5461bd50858e5f6c611f2246fe
-  data.tar.gz: edf1130a392a68a08fc95c1a29619e1a0399dbe0373c85048b6c45bba12a8dff88fb9ed84b1364c06ba5b5c9fa2c90e5da8fd083bd99b7d832a122cb72d3501e
+  metadata.gz: e46bf11d5142f63a5bde2fc5d6d0c34c5d352fc05e428e1c3bc05931e346c9cff163f664d611f2ea88c1d5af819ed9d09b2fde518d5fe4fd6629ab650626bb4f
+  data.tar.gz: ca25863674f4560506aca95d62739ca8998a0671cfc52561b99b1dac26f6c519d6ff19c1781b121a4f3b72d6902b5e00360f30418d954aac3a34ad3fbbe83515

data/CHANGELOG.md

@@ -4,6 +4,27 @@ 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    broadcast-ruby (0.8.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.8.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

@@ -839,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
@@ -854,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.
@@ -1488,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/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/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/version.rb

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

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