broadcast-ruby 0.2.0 → 0.4.0

data/lib/broadcast/delivery_method.rb

@@ -2,8 +2,21 @@
 
 module Broadcast
   class DeliveryMethod
+    # ActionMailer delivers transactional mail, so the unsubscribe link is off
+    # unless the host app opts back in via broadcast_settings. The option is
+    # consumed here rather than forwarded: Configuration would reject it.
+    DEFAULT_INCLUDE_UNSUBSCRIBE_LINK = false
+
     def initialize(settings = {})
-      @client = Client.new(**settings)
+      opts = settings.to_h.dup
+      @include_unsubscribe_link =
+        if opts.key?(:include_unsubscribe_link)
+          opts.delete(:include_unsubscribe_link)
+        else
+          DEFAULT_INCLUDE_UNSUBSCRIBE_LINK
+        end
+
+      @client = Client.new(**opts)
     end
 
     def deliver!(mail)
@@ -11,8 +24,15 @@ module Broadcast
         to: mail.to&.first,
         subject: mail.subject,
         body: extract_body(mail),
-        reply_to: mail.reply_to&.first
+        reply_to: mail.reply_to&.first,
+        html_body: (true if mail.html_part),
+        include_unsubscribe_link: @include_unsubscribe_link
       )
+    rescue Broadcast::WarningError
+      # The send succeeded — warnings_mode: :raise is about surfacing ignored
+      # parameters, not reporting a delivery failure. Wrapping it in
+      # DeliveryError would tell ActionMailer the mail didn't go out.
+      raise
     rescue Broadcast::Error => e
       raise DeliveryError, "Failed to deliver email: #{e.message}"
     end

data/lib/broadcast/errors.rb

@@ -13,11 +13,37 @@ module Broadcast
 
   class NotFoundError < APIError; end
 
-  class RateLimitError < APIError; end
+  # 409 — an in-flight request is already using this Idempotency-Key. The
+  # original request is still processing; retrying after a short pause will
+  # either replay its stored response or run fresh if it failed.
+  class ConflictError < APIError; end
+
+  class RateLimitError < APIError
+    # Seconds the server asked us to wait, parsed from the Retry-After header.
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil)
+      super(message)
+      @retry_after = retry_after
+    end
+  end
 
   class ValidationError < Error; end
 
   class TimeoutError < Error; end
 
   class DeliveryError < Error; end
+
+  # Raised instead of returning when config.warnings_mode is :raise and a 2xx
+  # response carried warnings. The request DID succeed — the write happened.
+  # Callers rescuing this must not assume anything was rolled back.
+  class WarningError < Error
+    attr_reader :warnings, :response
+
+    def initialize(warnings, response = nil)
+      @warnings = warnings
+      @response = response
+      super("API returned #{warnings.size} warning(s): #{warnings.join('; ')}")
+    end
+  end
 end

data/lib/broadcast/resources/autopilots.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # Autopilot — AI-generated newsletters.
+    #
+    # Requires the `autopilot_read` / `autopilot_write` token permissions.
+    class Autopilots < Base
+      # The API renders a configured key bullet-masked and never returns the
+      # real value. Writing a masked value back would replace a working
+      # credential with bullets, so it is stripped — same guard as
+      # EmailServers#update.
+      REDACTED_KEY_PATTERN = /\A•+\z/
+
+      def list(**params)
+        get('/api/v1/autopilots', params)
+      end
+
+      def get_autopilot(id)
+        get("/api/v1/autopilots/#{id}")
+      end
+
+      # Create an autopilot. Attrs are wrapped under `autopilot:` on the wire.
+      #
+      #   name:                  required, unique per channel
+      #   openrouter_api_key:    OpenRouter credential (write-only)
+      #   ai_model:              e.g. 'openai/gpt-4o'
+      #   schedule_frequency:    'daily' | 'weekly' | 'biweekly' | 'monthly'
+      #   schedule_day_of_week:, schedule_day_of_month:, schedule_time:, schedule_timezone:
+      #   copies_to_generate:    how many drafts each run produces
+      #   tone_description:, content_instructions:, newsletter_structure:
+      #   segment_ids:           array — restrict the newsletter's audience
+      def create(**attrs)
+        post('/api/v1/autopilots', { autopilot: attrs })
+      end
+
+      # Update an autopilot. A bullet-masked openrouter_api_key is dropped
+      # before sending; pass the real key to rotate it, or omit the field.
+      def update(id, **attrs)
+        patch("/api/v1/autopilots/#{id}", { autopilot: scrub_redacted_key(attrs) })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/autopilots/#{id}")
+      end
+
+      # --- Lifecycle ---
+
+      # Activate the autopilot so it runs on its schedule.
+      #
+      # Requires at least one active source, an API key, and a model. Raises
+      # Broadcast::ValidationError naming the missing prerequisites otherwise.
+      def activate(id)
+        post("/api/v1/autopilots/#{id}/activate")
+      end
+
+      def pause(id)
+        post("/api/v1/autopilots/#{id}/pause")
+      end
+
+      def deactivate(id)
+        post("/api/v1/autopilots/#{id}/deactivate")
+      end
+
+      # Queue a generation run now. Returns 202 with the created run — the work
+      # is asynchronous, so poll `runs` for progress rather than expecting a
+      # finished newsletter here.
+      def trigger_run(id)
+        post("/api/v1/autopilots/#{id}/trigger_run")
+      end
+
+      # --- Runs ---
+
+      # Generation runs, most recent first. Supports limit: and offset:.
+      def runs(id, **params)
+        get("/api/v1/autopilots/#{id}/runs", params)
+      end
+
+      private
+
+      def scrub_redacted_key(attrs)
+        key = attrs[:openrouter_api_key] || attrs['openrouter_api_key']
+        return attrs unless key.is_a?(String) && key.match?(REDACTED_KEY_PATTERN)
+
+        warn_redacted
+        attrs.reject { |name, _| name.to_sym == :openrouter_api_key }
+      end
+
+      def warn_redacted
+        msg = '[broadcast-ruby] Dropped redacted openrouter_api_key from update payload — ' \
+              'pass the real key or omit the field'
+        if @client.config.logger
+          @client.config.logger.warn(msg)
+        else
+          Kernel.warn(msg)
+        end
+      end
+    end
+  end
+end

data/lib/broadcast/resources/discovery.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # Introspection endpoints. Primarily built for AI agents and CLIs that need
+    # to discover what a token can do before acting, but equally useful for
+    # health checks and for failing fast on a misconfigured deploy.
+    class Discovery < Base
+      # Identity of the current token: label, type (channel_scoped or
+      # admin_cross_channel), per-resource permissions, and the resolved channel.
+      def whoami
+        get('/api/v1/whoami')
+      end
+
+      # Channel sender config, subscriber counts, and per-feature transmission
+      # readiness. Worth calling before a send — `readiness.broadcasts == false`
+      # means the channel has no usable email server or sender identity.
+      def status
+        get('/api/v1/status')
+      end
+
+      # Full capability manifest: platform version, token permissions, channel
+      # status, the endpoint list the token can reach, rate limit, and usage tips.
+      def prime
+        get('/api/v1/prime')
+      end
+
+      # Plain-text agent skill manifest (Markdown with YAML front matter),
+      # including the safety rules agents are expected to follow. Returns a
+      # String, not a Hash — this endpoint serves text/plain.
+      def skill
+        @client.request(:get, '/api/v1/skill', nil, raw: true)
+      end
+    end
+  end
+end

data/lib/broadcast/resources/global_suppressions.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # The installation-wide suppression list. Addresses on it never receive
+    # mail from any channel. All operations require an admin (system) API
+    # token — a channel token gets a 401.
+    #
+    # There is deliberately no `check` here: checking is a per-channel
+    # question (it reads the channel list too), so it lives on Suppressions.
+    class GlobalSuppressions < Base
+      # List global suppressions (250 per page, with `pagination` metadata;
+      # pass `page:`). Optional `email:` filters by partial match.
+      def list(**params)
+        get('/api/v1/global_suppressions.json', params)
+      end
+
+      # Add an address to the global list. Already-suppressed is a success
+      # (200 instead of 201).
+      def add(email)
+        post('/api/v1/global_suppressions.json', { email: email })
+      end
+
+      # Remove an address from the global list only. Channels that suppressed
+      # the same address on their own account keep their block.
+      def remove(email)
+        @client.request(:delete, '/api/v1/global_suppressions.json', { email: email })
+      end
+
+      # Add up to 10,000 addresses at once. Idempotent. Returns `added`,
+      # `already_suppressed`, and `invalid` counts.
+      def bulk_add(emails)
+        post('/api/v1/global_suppressions/bulk.json', { emails: emails })
+      end
+
+      # Remove up to 10,000 addresses at once. Returns `removed` and
+      # `not_found` counts.
+      def bulk_remove(emails)
+        @client.request(:delete, '/api/v1/global_suppressions/bulk.json', { emails: emails })
+      end
+    end
+  end
+end

data/lib/broadcast/resources/migration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # Read-only export endpoints under /api/migration/v1 — the surface behind
+    # backups and instance-to-instance migration.
+    #
+    # Two things differ from the v1 API:
+    #
+    # 1. **Admin tokens only.** Channel-scoped tokens are rejected outright;
+    #    the controller looks up AdminApiToken and nothing else.
+    # 2. **broadcast_channel_id is required on every call.** Set it once via
+    #    `Client.new(broadcast_channel_id:)` or `client.with_channel(id)` and
+    #    the gem attaches it automatically; otherwise pass it per call.
+    #
+    # Every list endpoint pages with `limit:` (1..250, default 250) and
+    # `offset:`, and returns `{"data" => [...], "pagination" => {...}}`.
+    class Migration < Base
+      # Endpoints that are a plain paginated list of the channel's records.
+      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
+      ].freeze
+
+      COLLECTIONS.each do |collection|
+        define_method(collection) do |**params|
+          get("/api/migration/v1/#{collection}", params)
+        end
+      end
+
+      # Export summary: format version, channel identity, per-resource counts,
+      # and recent-history totals. Call this first to size an export.
+      #
+      # @param days_history [Integer] window for the time-bounded counts
+      #   (broadcasts, receipts, histories). Server clamps to 1..365, default 90.
+      def manifest(**params)
+        get('/api/migration/v1/manifest', params)
+      end
+
+      # Binary contents of a stored file asset. Returns a String of bytes, not
+      # JSON — write it straight to disk.
+      def download_file_asset(id, **params)
+        @client.request(:get, "/api/migration/v1/file_assets/#{id}/download", params, raw: true)
+      end
+
+      # Pages through a collection, yielding each record.
+      #
+      #   client.migration.each_record(:subscribers) { |sub| csv << sub }
+      #
+      # Stops when the server reports `has_more: false`, so it stays correct if
+      # the page size is clamped server-side.
+      def each_record(collection, limit: 250, **params, &block)
+        return enum_for(:each_record, collection, limit: limit, **params) unless block_given?
+
+        offset = 0
+        loop do
+          page = public_send(collection, limit: limit, offset: offset, **params)
+          records = Array(page['data'])
+          records.each(&block)
+
+          pagination = page['pagination'] || {}
+          break unless pagination['has_more']
+
+          # Advance by what the server actually returned — it clamps `limit`.
+          advanced = pagination['limit'] || records.size
+          break if advanced.to_i.zero?
+
+          offset += advanced.to_i
+        end
+      end
+    end
+  end
+end

data/lib/broadcast/resources/opt_in_forms.rb

@@ -24,6 +24,18 @@ module Broadcast
       # Nested settings hashes (theme_settings, automation_settings, security_settings,
       # trigger_settings, widget_settings) and arrays (opt_in_form_blocks_attributes,
       # opt_in_post_submission_blocks_attributes) are passed through verbatim.
+      #
+      # Core:
+      #   label:, form_type:, widget_type:, enabled:, allowed_embedding_domains:
+      #
+      # Confirmation / welcome flow:
+      #   confirmation_email_template_id:            Template sent to confirm the address
+      #   welcome_email_template_id:                 Template sent after confirmation
+      #   confirmation_redirect_url:                 where to send the subscriber post-confirm
+      #   include_unsubscribe_link_in_confirmation:  boolean
+      #
+      # Custom fields declared in opt_in_form_blocks_attributes support a
+      # multi-line variant, which renders as a textarea on the hosted form.
       def create(**attrs)
         post('/api/v1/opt_in_forms', { opt_in_form: attrs })
       end

data/lib/broadcast/resources/subscribers.rb

@@ -3,6 +3,22 @@
 module Broadcast
   module Resources
     class Subscribers < Base
+      # List subscribers (250 per page, with `pagination` metadata; pass `page:`).
+      #
+      # Filters, all optional and combinable:
+      #   is_active:            true | false
+      #   source:               exact match on the source string
+      #   created_after:        ISO-8601 timestamp
+      #   created_before:       ISO-8601 timestamp
+      #   tags:                 array — AND logic, subscriber must have all of them
+      #   email:                partial (case-insensitive) match, not exact
+      #   confirmation_status:  'confirmed' | 'unconfirmed'
+      #   custom_data:          hash — JSONB containment, e.g. { plan: 'pro' }
+      #
+      # An unparseable created_after/created_before is *ignored* by the server
+      # rather than rejected; it comes back as a `parameter_ignored` warning on
+      # the response, so a bad timestamp silently widens the result set unless
+      # you check `result.warnings`.
       def list(**params)
         get('/api/v1/subscribers.json', params)
       end
@@ -22,6 +38,14 @@ module Broadcast
       #                                When set, the subscriber is created in unconfirmed state
       #                                and a confirmation email is queued.
       #   confirmation_template_id:    custom confirmation template (used with double_opt_in: true)
+      #
+      # Admin tokens only:
+      #   confirmed_at:                backdate the confirmation timestamp on create.
+      #                                Intended for migrating an already-confirmed list off
+      #                                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)`.
       def create(**attrs)
         double_opt_in = attrs.delete(:double_opt_in)
         confirmation_template_id = attrs.delete(:confirmation_template_id)

data/lib/broadcast/resources/suppressions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    # The current channel's suppression list. Addresses on it never receive
+    # broadcasts, sequences, or transactionals from this channel.
+    #
+    # The installation-wide list is a separate resource — see
+    # GlobalSuppressions — but `check` reads across both on purpose: it
+    # answers the question an integration actually asks, "will this address
+    # receive mail?".
+    class Suppressions < Base
+      # List the channel's suppressions (250 per page, with `pagination`
+      # metadata; pass `page:`). Optional `email:` filters by partial,
+      # case-insensitive match.
+      def list(**params)
+        get('/api/v1/suppressions.json', params)
+      end
+
+      # Add an address to the channel's suppression list.
+      #
+      # Adding an address that is already suppressed is a success (the server
+      # answers 200 instead of 201), so callers do not have to check first.
+      def add(email)
+        post('/api/v1/suppressions.json', { email: email })
+      end
+
+      # Remove an address from the channel's suppression list. Returns
+      # `removed: false` (not an error) when the address was not on it.
+      # Does not touch the global list.
+      def remove(email)
+        @client.request(:delete, '/api/v1/suppressions.json', { email: email })
+      end
+
+      # Add up to 10,000 addresses at once. Idempotent: a retried batch cannot
+      # duplicate. Returns `added`, `already_suppressed`, and `invalid` counts.
+      def bulk_add(emails)
+        post('/api/v1/suppressions/bulk.json', { emails: emails })
+      end
+
+      # Remove up to 10,000 addresses at once. Returns `removed` and
+      # `not_found` counts.
+      def bulk_remove(emails)
+        @client.request(:delete, '/api/v1/suppressions/bulk.json', { emails: emails })
+      end
+
+      # Will this address receive mail? Reads across both the global and the
+      # channel list — a globally blocked address reports `suppressed: true`
+      # here even though it is absent from the channel's own list. The
+      # response's `scope` says which list matched.
+      def check(email)
+        get('/api/v1/suppressions/check.json', { email: email })
+      end
+    end
+  end
+end

data/lib/broadcast/resources/templates.rb

@@ -11,6 +11,23 @@ module Broadcast
         get("/api/v1/templates/#{id}")
       end
 
+      # Create a template. Attrs are wrapped under `template:` on the wire.
+      #
+      # Content:
+      #   label:, subject:, preheader:, body:, html_body:
+      #
+      # Confirmation templates (double opt-in):
+      #   template_purpose:          marks the template's role, e.g. 'confirmation'
+      #   confirmation_text:         copy shown in the confirmation email
+      #   default_confirmation:      make this the channel's default confirmation template
+      #   confirmation_page_settings: per-state page copy, keyed by state, each
+      #                              taking { heading:, body: } — e.g.
+      #                              { 'confirmed' => { heading: 'You're in',
+      #                                                 body: 'Thanks for confirming.' },
+      #                                'expired'   => { heading: 'Link expired', body: '...' } }
+      #
+      # Anything the server doesn't recognize comes back as an
+      # `unrecognized_parameter` warning on the response rather than an error.
       def create(**attrs)
         post('/api/v1/templates', { template: attrs })
       end

data/lib/broadcast/resources/transactionals.rb

@@ -3,6 +3,8 @@
 module Broadcast
   module Resources
     class Transactionals < Base
+      MAX_IDEMPOTENCY_KEY_LENGTH = 255
+
       # Send a transactional email.
       #
       # Required:
@@ -20,11 +22,29 @@ module Broadcast
       #                                Holds the email until the recipient confirms.
       #   confirmation_template_id:    custom confirmation template (used with double_opt_in: true)
       #   subscriber:                  { first_name:, last_name: } — populates Subscriber on first send
+      #   idempotency_key:             see below
+      #
+      # Idempotency
+      # -----------
+      # Pass `idempotency_key:` to make a retry safe. The server stores the
+      # response for 24 hours keyed on (token, key) and replays it rather than
+      # sending a second email. Check `result.idempotent_replay?` to tell a
+      # replay from a fresh send.
+      #
+      #   client.transactionals.create(to: 'a@b.com', subject: 'Receipt',
+      #                                body: '<p>Thanks</p>',
+      #                                idempotency_key: "receipt-#{order.id}")
+      #
+      # The key is part of a fingerprint over method + full path + body:
+      #   - same key, same payload, still running   -> Broadcast::ConflictError (409)
+      #   - same key, *different* payload           -> Broadcast::ValidationError (422)
+      # That 422 means "this key was already used for something else", not that
+      # the email was invalid — don't retry it with the same key.
       # rubocop:disable Metrics/ParameterLists -- mirrors the API's flat param surface
       def create(to:, subject: nil, body: nil, reply_to: nil, preheader: nil,
                  template_id: nil, include_unsubscribe_link: nil,
                  double_opt_in: nil, confirmation_template_id: nil,
-                 subscriber: nil, **extra)
+                 subscriber: nil, idempotency_key: nil, **extra)
         # rubocop:enable Metrics/ParameterLists
         payload = { to: to }
         payload[:subject] = subject unless subject.nil?
@@ -38,12 +58,29 @@ module Broadcast
         payload[:subscriber] = subscriber unless subscriber.nil?
         payload.merge!(extra) unless extra.empty?
 
-        post('/api/v1/transactionals.json', payload)
+        @client.request(:post, '/api/v1/transactionals.json', payload,
+                        headers: idempotency_headers(idempotency_key))
       end
 
       def get_transactional(id)
         get("/api/v1/transactionals/#{id}.json")
       end
+
+      private
+
+      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/response.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module Broadcast
+  # A single entry from the API's `warnings` array (docs: api-response-warnings).
+  # The API raises these on successful 2xx responses when it accepted the request
+  # but ignored part of it — an unrecognized parameter, a parameter that only
+  # applies in another mode, a value the server overrode.
+  #
+  # `param` is a dot-path to the offending parameter (e.g. "subscriber.foo").
+  # The API never includes submitted values, so a warning is safe to log.
+  Warning = Struct.new(:code, :param, :message) do
+    def to_s
+      param ? "[#{code}] #{param}: #{message}" : "[#{code}] #{message}"
+    end
+  end
+
+  # Parsed X-RateLimit-* response headers. `reset` is the time the current
+  # window rolls over, not a duration.
+  RateLimit = Struct.new(:limit, :remaining, :reset)
+
+  # The value returned by every JSON API call.
+  #
+  # Response subclasses Hash rather than wrapping it, so everything that worked
+  # against the raw parsed body still works — `result['id']`, `result.is_a?(Hash)`,
+  # `result.dig(...)`, equality against a plain Hash. The response metadata the
+  # API sends alongside the body is exposed as extra readers.
+  #
+  #   result = client.subscribers.create(email: 'user@example.com', foo: 'bar')
+  #   result['id']                  # => 42        (unchanged from v0.2)
+  #   result.warnings               # => [#<Warning code="unrecognized_parameter" ...>]
+  #   result.rate_limit.remaining   # => 118
+  #   result.status                 # => 201
+  #
+  # Non-Hash JSON bodies (a bare array) are returned as-is and carry no metadata.
+  class Response < Hash
+    attr_reader :status, :headers
+
+    class << self
+      # Wraps a parsed JSON body when it is a Hash; passes anything else through.
+      def build(parsed, status:, headers: {})
+        return parsed unless parsed.is_a?(::Hash)
+
+        response = new
+        response.replace(parsed)
+        response.attach_metadata(status: status, headers: headers)
+        response
+      end
+    end
+
+    # @api private — set once by .build immediately after construction
+    def attach_metadata(status:, headers:)
+      @status = status
+      @headers = headers
+      self
+    end
+
+    def warnings
+      @warnings ||= Array(self['warnings']).filter_map do |entry|
+        next unless entry.is_a?(::Hash)
+
+        Warning.new(code: entry['code'], param: entry['param'], message: entry['message'])
+      end
+    end
+
+    def warnings?
+      !warnings.empty?
+    end
+
+    def rate_limit
+      return @rate_limit if defined?(@rate_limit)
+
+      limit = header('x-ratelimit-limit')
+      @rate_limit = if limit.nil?
+                      nil
+                    else
+                      RateLimit.new(
+                        limit: limit.to_i,
+                        remaining: header('x-ratelimit-remaining')&.to_i,
+                        reset: parse_time(header('x-ratelimit-reset'))
+                      )
+                    end
+    end
+
+    # True when the API replayed a stored response for a repeated
+    # Idempotency-Key rather than performing the write again.
+    def idempotent_replay?
+      header('idempotency-replayed') == 'true'
+    end
+
+    private
+
+    def header(name)
+      (@headers || {})[name]
+    end
+
+    def parse_time(value)
+      value && Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/broadcast/version.rb

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