broadcast-ruby 0.2.0 → 0.3.0

data/lib/broadcast/configuration.rb

@@ -2,32 +2,81 @@
 
 module Broadcast
   class Configuration
+    # How to handle the `warnings` array the API returns on successful writes
+    # (docs: api-response-warnings):
+    #   :log    — warn through `logger` if one is set (default)
+    #   :raise  — raise Broadcast::WarningError; note the write already happened
+    #   :ignore — leave them on the response for the caller to inspect
+    WARNINGS_MODES = %i[log raise ignore].freeze
+
+    # Env vars use the same names as the Broadcast CLI's ~/.config/broadcast/config,
+    # so a machine set up for the CLI can drive the gem with no extra config.
+    ENV_HOST = 'BROADCAST_HOST'
+    ENV_TOKEN = 'BROADCAST_API_TOKEN'
+
     attr_accessor :api_token,
                   :host,
                   :timeout,
                   :open_timeout,
                   :retry_attempts,
                   :retry_delay,
+                  :max_retry_delay,
+                  :warnings_mode,
                   :logger,
                   :debug,
                   :broadcast_channel_id
 
     def initialize
-      @api_token = nil
-      @host = 'https://sendbroadcast.com'
+      @api_token = ENV.fetch(ENV_TOKEN, nil)
+      # No default host. Broadcast is self-hosted-first — every instance lives
+      # at its own domain, so any built-in guess is wrong for nearly everyone.
+      @host = ENV.fetch(ENV_HOST, nil)
       @timeout = 30
       @open_timeout = 10
       @retry_attempts = 3
       @retry_delay = 1
+      # Ceiling for a server-supplied Retry-After. Without it a long rate-limit
+      # window would block the caller for as long as the server asked.
+      @max_retry_delay = 30
+      @warnings_mode = :log
       @logger = nil
       @debug = false
       @broadcast_channel_id = nil
     end
 
     def validate!
-      raise ConfigurationError, 'api_token is required' if api_token.nil? || api_token.to_s.strip.empty?
+      raise ConfigurationError, 'api_token is required' if blank?(api_token)
+      raise ConfigurationError, host_missing_message if blank?(host)
+
+      self.host = host.to_s.strip.chomp('/')
+      validate_host_scheme!
+      validate_warnings_mode!
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.strip.empty?
+    end
+
+    def host_missing_message
+      "host is required — point it at your Broadcast instance, e.g. \
+Broadcast::Client.new(api_token: '...', host: 'https://mail.example.com'). \
+You can also set the #{ENV_HOST} environment variable."
+    end
+
+    def validate_host_scheme!
+      return if host.start_with?('http://', 'https://')
+
+      raise ConfigurationError, "host must include a scheme (http:// or https://), got #{host.inspect}"
+    end
+
+    def validate_warnings_mode!
+      self.warnings_mode = warnings_mode.to_sym
+      return if WARNINGS_MODES.include?(warnings_mode)
 
-      self.host = host.chomp('/') if host&.end_with?('/')
+      raise ConfigurationError,
+            "warnings_mode must be one of #{WARNINGS_MODES.join(', ')}, got #{warnings_mode.inspect}"
     end
   end
 end

data/lib/broadcast/connection.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Broadcast
+  # HTTP transport. Owns request building, response/error mapping, retries,
+  # redirects, and debug logging. Split out of Client so Client stays a thin
+  # facade over configuration and resource sub-clients.
+  class Connection
+    MAX_REDIRECTS = 3
+    REDIRECT_CODES = [301, 302, 307, 308].freeze
+
+    ERROR_MAPPING = {
+      401 => [AuthenticationError, 'Authentication failed'],
+      403 => [AuthorizationError, 'Not authorized'],
+      404 => [NotFoundError, 'Resource not found'],
+      409 => [ConflictError, 'A request with this Idempotency-Key is still being processed'],
+      422 => [ValidationError, 'Validation failed']
+    }.freeze
+    private_constant :ERROR_MAPPING
+
+    def initialize(config)
+      @config = config
+      @debug_logger = DebugLogger.new(config)
+    end
+
+    # @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)
+      uri = build_uri(path, method, payload)
+      context = { headers: headers, raw: raw, redirects: 0 }
+
+      retry_with_backoff { execute(method, uri, payload, context) }
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise Broadcast::TimeoutError, "Request timeout: #{e.message}"
+    end
+
+    private
+
+    def build_uri(path, method, payload)
+      uri = URI("#{@config.host}#{path}")
+      uri.query = URI.encode_www_form(flatten_params(payload)) if method == :get && payload_present?(payload)
+      uri
+    end
+
+    def execute(method, uri, payload, context)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+
+      req = build_request(method, uri, context[:headers])
+      req.body = payload.to_json if method != :get && payload_present?(payload)
+
+      @debug_logger.request(req, method == :get ? nil : payload)
+      response = http.request(req)
+      @debug_logger.response(response)
+
+      return follow_redirect(response, method, uri, context) if redirect?(response)
+
+      handle_response(response, raw: context[:raw])
+    end
+
+    # --- Redirects -----------------------------------------------------------
+    #
+    # A redirect nearly always means a misconfigured `host` (http vs https, a
+    # bare apex that redirects to www, a stale domain). Two things are never
+    # followed:
+    #
+    #   - writes, because replaying a send against an unexpected origin is worse
+    #     than failing; and
+    #   - anything that changes host, because every request carries
+    #     `Authorization: Bearer <token>` and following would hand the API token
+    #     to whatever the redirect points at.
+    #
+    # Both raise with the destination named, so a misconfigured host diagnoses
+    # itself instead of failing mysteriously.
+
+    def redirect?(response)
+      REDIRECT_CODES.include?(response.code.to_i)
+    end
+
+    def follow_redirect(response, method, uri, context)
+      location = response['location']
+      redirects = context[:redirects]
+
+      if method != :get
+        raise APIError,
+              "Host redirected #{method.to_s.upcase} #{uri} to #{location || '(no Location header)'}. " \
+              'Set `host` to the final URL — writes are not followed automatically.'
+      end
+
+      raise APIError, "Redirect from #{uri} had no Location header" if location.nil?
+      raise APIError, "Too many redirects (#{MAX_REDIRECTS}) starting at #{uri}" if redirects >= MAX_REDIRECTS
+
+      target = URI.join(uri, location)
+      raise APIError, cross_host_redirect_message(uri, target) unless same_host?(uri, target)
+
+      # Query string is already baked into the current URI; don't re-append it.
+      execute(:get, target, nil, context.merge(redirects: redirects + 1))
+    end
+
+    def same_host?(from, to)
+      from.host&.downcase == to.host&.downcase
+    end
+
+    def cross_host_redirect_message(from, target)
+      "Host redirected #{from} to a different host (#{target}). Not following it — " \
+        'the request carries your API token. Set `host` to the correct instance URL.'
+    end
+
+    # --- Requests ------------------------------------------------------------
+
+    def build_request(method, uri, extra_headers)
+      klass = case method
+              when :get then Net::HTTP::Get
+              when :post then Net::HTTP::Post
+              when :patch then Net::HTTP::Patch
+              when :delete then Net::HTTP::Delete
+              else raise ArgumentError, "Unsupported HTTP method: #{method}"
+              end
+
+      req = klass.new(uri)
+      req['Authorization'] = "Bearer #{@config.api_token}"
+      req['Content-Type'] = 'application/json'
+      req['User-Agent'] = "broadcast-ruby/#{Broadcast::VERSION}"
+      extra_headers.each { |key, value| req[key.to_s] = value.to_s unless value.nil? }
+      req
+    end
+
+    def payload_present?(payload)
+      payload.is_a?(Hash) && payload.any?
+    end
+
+    # --- Responses -----------------------------------------------------------
+
+    def handle_response(response, raw:)
+      code = response.code.to_i
+      return build_success(response, raw: raw) if code.between?(200, 299)
+
+      raise_rate_limit_error(response) if code == 429
+
+      if (mapping = ERROR_MAPPING[code])
+        klass, default = mapping
+        raise klass, parse_error(response) || default
+      end
+
+      raise APIError, parse_error(response) || "Server error (#{code})" if code >= 500
+
+      raise APIError, parse_error(response) || "Unexpected response: #{code}"
+    end
+
+    def build_success(response, raw:)
+      return raw_body(response) if raw
+
+      result = Response.build(
+        parse_success_body(response),
+        status: response.code.to_i,
+        headers: extract_headers(response)
+      )
+      handle_warnings(result)
+      result
+    end
+
+    # Raw endpoints serve two very different things: text (/api/v1/skill) and
+    # binary file assets. Trusting the body's default encoding would tag PNG
+    # bytes as UTF-8 and blow up on the first regex match, so only keep a text
+    # encoding when the server actually declared a charset.
+    def raw_body(response)
+      body = response.body.to_s
+      return body if response.type_params['charset']
+
+      body.dup.force_encoding(Encoding::BINARY)
+    end
+
+    def raise_rate_limit_error(response)
+      retry_after = response['retry-after']&.to_i
+      raise RateLimitError.new(parse_error(response) || 'Rate limit exceeded', retry_after: retry_after)
+    end
+
+    def extract_headers(response)
+      headers = {}
+      response.each_header { |key, value| headers[key.downcase] = value }
+      headers
+    end
+
+    def parse_success_body(response)
+      return {} if response.body.nil? || response.body.strip.empty?
+
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      # A 2xx that isn't JSON (an HTML error page from a proxy, say). Surface it
+      # as an empty body rather than exploding — `raw: true` is the way to read
+      # non-JSON endpoints deliberately.
+      {}
+    end
+
+    def parse_error(response)
+      body = JSON.parse(response.body)
+      body['error'] || format_errors(body['errors'])
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    # ActiveModel errors arrive as {"field" => ["msg", ...]}
+    def format_errors(errors)
+      return nil if errors.nil?
+      return errors.join(', ') if errors.is_a?(Array)
+      return nil unless errors.is_a?(Hash)
+
+      errors.map { |field, messages| "#{field} #{Array(messages).join(', ')}" }.join('; ')
+    end
+
+    # --- Warnings ------------------------------------------------------------
+
+    def handle_warnings(result)
+      return unless result.is_a?(Response) && result.warnings?
+
+      case @config.warnings_mode
+      when :raise then raise WarningError.new(result.warnings, result)
+      when :log then @debug_logger.warnings(result.warnings)
+      end
+    end
+
+    # --- Retries -------------------------------------------------------------
+
+    def retry_with_backoff
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise if attempts >= @config.retry_attempts
+
+        sleep(@config.retry_delay * attempts)
+        retry
+      rescue RateLimitError => e
+        raise if attempts >= @config.retry_attempts
+
+        sleep(rate_limit_delay(e, attempts))
+        retry
+      rescue APIError => e
+        raise unless attempts < @config.retry_attempts && e.message.include?('Server error')
+
+        sleep(@config.retry_delay * attempts)
+        retry
+      end
+    end
+
+    # Honour Retry-After when the server sent one, but never sleep longer than
+    # max_retry_delay — a wide rate-limit window shouldn't hang the caller.
+    def rate_limit_delay(error, attempts)
+      requested = error.retry_after || (@config.retry_delay * attempts)
+      [requested, @config.max_retry_delay].min
+    end
+
+    # --- Params --------------------------------------------------------------
+
+    def flatten_params(params)
+      result = []
+      params.each do |key, value|
+        case value
+        when Array
+          value.each { |v| result << ["#{key}[]", v.to_s] }
+        when Hash
+          value.each { |k, v| result << ["#{key}[#{k}]", v.to_s] }
+        when nil
+          next
+        else
+          result << [key.to_s, value.to_s]
+        end
+      end
+      result
+    end
+  end
+end

data/lib/broadcast/debug_logger.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Broadcast
+  # Debug logging for HTTP traffic, kept separate from Connection so the
+  # redaction rules live in one obvious place.
+  #
+  # Request bodies routinely carry SMTP passwords and provider API keys
+  # (email server create/update), so nothing is logged verbatim — matching keys
+  # are replaced before the body is serialized.
+  class DebugLogger
+    SENSITIVE_KEYS = %w[
+      smtp_password aws_access_key_id aws_secret_access_key
+      outbound_aws_access_key_id outbound_aws_secret_access_key
+      postmark_api_token inboxroad_api_token smtp_com_api_key
+      api_key api_token password secret
+    ].freeze
+
+    def initialize(config)
+      @config = config
+    end
+
+    def enabled?
+      @config.debug && !@config.logger.nil?
+    end
+
+    def request(http_request, body)
+      return unless enabled?
+
+      @config.logger.debug("[Broadcast] #{http_request.method} #{http_request.uri}")
+      return unless body.is_a?(Hash) && body.any?
+
+      @config.logger.debug("[Broadcast] Body: #{redact(body).to_json}")
+    end
+
+    def response(http_response)
+      return unless enabled?
+
+      @config.logger.debug("[Broadcast] Response: #{http_response.code} #{http_response.body}")
+    end
+
+    def warnings(warnings)
+      return unless @config.logger
+
+      warnings.each { |warning| @config.logger.warn("[Broadcast] #{warning}") }
+    end
+
+    private
+
+    def redact(value)
+      case value
+      when Hash
+        value.to_h do |key, nested|
+          SENSITIVE_KEYS.include?(key.to_s) ? [key, '[REDACTED]'] : [key, redact(nested)]
+        end
+      when Array
+        value.map { |item| redact(item) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/broadcast/delivery_method.rb

@@ -13,6 +13,11 @@ module Broadcast
         body: extract_body(mail),
         reply_to: mail.reply_to&.first
       )
+    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/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