RubyGems - broadcast-ruby - Versions diffs - 0.2.0 → 0.4.0 - Mend

broadcast-ruby 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (26) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +146 -0
data/Gemfile.lock +3 -2
data/README.md +434 -22
data/SDK-COVERAGE.md +469 -0
data/lib/broadcast/client.rb +65 -138
data/lib/broadcast/configuration.rb +53 -4
data/lib/broadcast/connection.rb +278 -0
data/lib/broadcast/debug_logger.rb +64 -0
data/lib/broadcast/delivery_method.rb +22 -2
data/lib/broadcast/errors.rb +27 -1
data/lib/broadcast/resources/autopilots.rb +100 -0
data/lib/broadcast/resources/discovery.rb +36 -0
data/lib/broadcast/resources/global_suppressions.rb +43 -0
data/lib/broadcast/resources/migration.rb +75 -0
data/lib/broadcast/resources/opt_in_forms.rb +12 -0
data/lib/broadcast/resources/subscribers.rb +24 -0
data/lib/broadcast/resources/suppressions.rb +56 -0
data/lib/broadcast/resources/templates.rb +17 -0
data/lib/broadcast/resources/transactionals.rb +39 -2
data/lib/broadcast/response.rb +104 -0
data/lib/broadcast/version.rb +1 -1
data/lib/broadcast/webhook.rb +34 -0
data/lib/broadcast.rb +8 -0
metadata +11 -3
data/.rubocop.yml +0 -50

data/lib/broadcast/client.rb CHANGED Viewed

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
-require 'net/http'
-require 'json'
-require 'uri'
 module Broadcast
   class Client
     CHANNEL_OVERRIDE_KEY = :__broadcast_ruby_channel_override
@@ -14,6 +10,7 @@ module Broadcast
       @config = Configuration.new
       settings.each { |k, v| @config.public_send(:"#{k}=", v) }
       @config.validate!
+      @connection = Connection.new(@config)
     end
     # --- Channel scoping (admin/system tokens) ---
@@ -38,15 +35,48 @@ module Broadcast
     # Thin convenience wrapper around `transactionals.create`. Use
     # `client.transactionals.create` directly for template_id, double_opt_in,
-    # preheader, and other advanced options.
-    def send_email(to:, subject: nil, body: nil, reply_to: nil)
-      transactionals.create(to: to, subject: subject, body: body, reply_to: reply_to)
+    # preheader, idempotency_key, and other advanced options.
+    # `html_body` tells Broadcast the body is already HTML. Without it the send
+    # is recorded as plain text and the payload is wrapped in Broadcast's own
+    # <html><body> shell, so an HTML mail arrives as two nested documents.
+    #
+    # `include_unsubscribe_link` lets the caller suppress the unsubscribe
+    # footer and List-Unsubscribe header. Transactional mail wants that off: a
+    # one-click unsubscribe on a password reset marks the person unsubscribed
+    # and silently drops them from every sequence and broadcast.
+    # rubocop:disable Metrics/ParameterLists -- mirrors the API's flat param surface
+    def send_email(to:, subject: nil, body: nil, reply_to: nil,
+                   html_body: nil, include_unsubscribe_link: nil)
+      # rubocop:enable Metrics/ParameterLists
+      opts = { to: to, subject: subject, body: body, reply_to: reply_to }
+      opts[:html_body] = html_body unless html_body.nil?
+      opts[:include_unsubscribe_link] = include_unsubscribe_link unless include_unsubscribe_link.nil?
+      transactionals.create(**opts)
     end
     def get_email(id)
       transactionals.get_transactional(id)
     end
+    # --- Discovery (convenience shims) ---
+    def whoami
+      discovery.whoami
+    end
+    def status
+      discovery.status
+    end
+    def prime
+      discovery.prime
+    end
+    def skill
+      discovery.skill
+    end
     # --- Resource sub-clients ---
     def subscribers
@@ -85,14 +115,36 @@ module Broadcast
       @email_servers ||= Resources::EmailServers.new(self)
     end
+    def autopilots
+      @autopilots ||= Resources::Autopilots.new(self)
+    end
+    def discovery
+      @discovery ||= Resources::Discovery.new(self)
+    end
+    # The current channel's suppression list (plus `check`, which reads the
+    # global list too).
+    def suppressions
+      @suppressions ||= Resources::Suppressions.new(self)
+    end
+    # The installation-wide suppression list. Requires an admin (system) API
+    # token.
+    def global_suppressions
+      @global_suppressions ||= Resources::GlobalSuppressions.new(self)
+    end
+    # Read-only export endpoints under /api/migration/v1. Requires an admin
+    # (system) API token.
+    def migration
+      @migration ||= Resources::Migration.new(self)
+    end
     # @api private
-    def request(method, path, body_or_params = nil)
+    def request(method, path, body_or_params = nil, headers: {}, raw: false)
       payload = inject_channel_scope(body_or_params)
-      uri = build_uri(path, method, payload)
-      retry_with_backoff { execute(method, uri, payload) }
-    rescue Net::OpenTimeout, Net::ReadTimeout => e
-      raise Broadcast::TimeoutError, "Request timeout: #{e.message}"
+      @connection.request(method, path, payload, headers: headers, raw: raw)
     end
     private
@@ -117,130 +169,5 @@ module Broadcast
       payload[:broadcast_channel_id] = channel_id
       payload
     end
-    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)
-      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)
-      req.body = payload.to_json if method != :get && payload_present?(payload)
-      log_request(req, method == :get ? nil : payload) if @config.debug
-      response = http.request(req)
-      log_response(response) if @config.debug
-      handle_response(response)
-    end
-    def payload_present?(payload)
-      payload.is_a?(Hash) && payload.any?
-    end
-    def build_request(method, uri)
-      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}"
-      req
-    end
-    ERROR_MAPPING = {
-      401 => [AuthenticationError, 'Authentication failed'],
-      403 => [AuthorizationError, 'Not authorized'],
-      404 => [NotFoundError, 'Resource not found'],
-      422 => [ValidationError, 'Validation failed'],
-      429 => [RateLimitError, 'Rate limit exceeded']
-    }.freeze
-    SERVER_ERROR_CODES = [500, 502, 503, 504].freeze
-    private_constant :ERROR_MAPPING, :SERVER_ERROR_CODES
-    def handle_response(response)
-      code = response.code.to_i
-      return parse_success_body(response) if [200, 201].include?(code)
-      if (mapping = ERROR_MAPPING[code])
-        klass, default = mapping
-        raise klass, parse_error(response) || default
-      end
-      raise APIError, parse_error(response) || "Server error (#{code})" if SERVER_ERROR_CODES.include?(code)
-      raise APIError, parse_error(response) || "Unexpected response: #{code}"
-    end
-    def parse_success_body(response)
-      return {} if response.body.nil? || response.body.strip.empty?
-      JSON.parse(response.body)
-    end
-    def parse_error(response)
-      JSON.parse(response.body)['error']
-    rescue JSON::ParserError
-      nil
-    end
-    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 APIError => e
-        raise unless attempts < @config.retry_attempts && e.message.include?('Server error')
-        sleep(@config.retry_delay * attempts)
-        retry
-      end
-    end
-    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
-    def log_request(request, body)
-      return unless @config.logger
-      @config.logger.debug("[Broadcast] #{request.method} #{request.uri}")
-      @config.logger.debug("[Broadcast] Body: #{body.to_json}") if body.is_a?(Hash) && body.any?
-    end
-    def log_response(response)
-      return unless @config.logger
-      @config.logger.debug("[Broadcast] Response: #{response.code} #{response.body}")
-    end
   end
 end

data/lib/broadcast/configuration.rb CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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