broadcast-ruby 0.1.0

data/lib/broadcast/client.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Broadcast
+  class Client
+    attr_reader :config
+
+    def initialize(**settings)
+      @config = Configuration.new
+      settings.each { |k, v| @config.public_send(:"#{k}=", v) }
+      @config.validate!
+    end
+
+    # --- Transactional email ---
+
+    def send_email(to:, subject:, body:, reply_to: nil)
+      payload = { to: to, subject: subject, body: body }
+      payload[:reply_to] = reply_to if reply_to
+      request(:post, '/api/v1/transactionals.json', payload)
+    end
+
+    def get_email(id)
+      request(:get, "/api/v1/transactionals/#{id}.json")
+    end
+
+    # --- Resource sub-clients ---
+
+    def subscribers
+      @subscribers ||= Resources::Subscribers.new(self)
+    end
+
+    def sequences
+      @sequences ||= Resources::Sequences.new(self)
+    end
+
+    def broadcasts
+      @broadcasts ||= Resources::Broadcasts.new(self)
+    end
+
+    def segments
+      @segments ||= Resources::Segments.new(self)
+    end
+
+    def templates
+      @templates ||= Resources::Templates.new(self)
+    end
+
+    def webhook_endpoints
+      @webhook_endpoints ||= Resources::WebhookEndpoints.new(self)
+    end
+
+    # @api private
+    def request(method, path, body_or_params = nil)
+      uri = URI("#{@config.host}#{path}")
+
+      if method == :get && body_or_params.is_a?(Hash) && body_or_params.any?
+        uri.query = URI.encode_www_form(flatten_params(body_or_params))
+      end
+
+      retry_with_backoff do
+        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 = body_or_params.to_json if method != :get && body_or_params.is_a?(Hash) && body_or_params.any?
+
+        log_request(req, method == :get ? nil : body_or_params) if @config.debug
+
+        response = http.request(req)
+        log_response(response) if @config.debug
+        handle_response(response)
+      end
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise Broadcast::TimeoutError, "Request timeout: #{e.message}"
+    end
+
+    private
+
+    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
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200, 201
+        return {} if response.body.nil? || response.body.strip.empty?
+
+        JSON.parse(response.body)
+      when 401
+        raise AuthenticationError, parse_error(response) || 'Authentication failed'
+      when 404
+        raise NotFoundError, parse_error(response) || 'Resource not found'
+      when 422
+        raise ValidationError, parse_error(response) || 'Validation failed'
+      when 429
+        raise RateLimitError, parse_error(response) || 'Rate limit exceeded'
+      when 500, 502, 503, 504
+        raise APIError, parse_error(response) || "Server error (#{response.code})"
+      else
+        raise APIError, parse_error(response) || "Unexpected response: #{response.code}"
+      end
+    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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Broadcast
+  class Configuration
+    attr_accessor :api_token,
+                  :host,
+                  :timeout,
+                  :open_timeout,
+                  :retry_attempts,
+                  :retry_delay,
+                  :logger,
+                  :debug
+
+    def initialize
+      @api_token = nil
+      @host = 'https://sendbroadcast.com'
+      @timeout = 30
+      @open_timeout = 10
+      @retry_attempts = 3
+      @retry_delay = 1
+      @logger = nil
+      @debug = false
+    end
+
+    def validate!
+      raise ConfigurationError, 'api_token is required' if api_token.nil? || api_token.to_s.strip.empty?
+
+      self.host = host.chomp('/') if host&.end_with?('/')
+    end
+  end
+end

data/lib/broadcast/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Broadcast
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class APIError < Error; end
+
+  class AuthenticationError < APIError; end
+
+  class NotFoundError < APIError; end
+
+  class RateLimitError < APIError; end
+
+  class ValidationError < Error; end
+
+  class TimeoutError < Error; end
+end

data/lib/broadcast/resources/base.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def get(path, params = {})
+        @client.request(:get, path, params)
+      end
+
+      def post(path, body = {})
+        @client.request(:post, path, body)
+      end
+
+      def patch(path, body = {})
+        @client.request(:patch, path, body)
+      end
+    end
+  end
+end

data/lib/broadcast/resources/broadcasts.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Broadcasts < Base
+      def list(**params)
+        get('/api/v1/broadcasts', params)
+      end
+
+      def get_broadcast(id)
+        get("/api/v1/broadcasts/#{id}")
+      end
+
+      def create(**attrs)
+        post('/api/v1/broadcasts', attrs)
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/broadcasts/#{id}", attrs)
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/broadcasts/#{id}")
+      end
+
+      def send_broadcast(id)
+        post("/api/v1/broadcasts/#{id}/send_broadcast")
+      end
+
+      def schedule(id, scheduled_send_at:, scheduled_timezone:)
+        post("/api/v1/broadcasts/#{id}/schedule_broadcast", {
+               scheduled_send_at: scheduled_send_at,
+               scheduled_timezone: scheduled_timezone
+             })
+      end
+
+      def cancel_schedule(id)
+        post("/api/v1/broadcasts/#{id}/cancel_schedule")
+      end
+
+      def statistics(id)
+        get("/api/v1/broadcasts/#{id}/statistics")
+      end
+
+      def statistics_timeline(id, **params)
+        get("/api/v1/broadcasts/#{id}/statistics/timeline", params)
+      end
+
+      def statistics_links(id, **params)
+        get("/api/v1/broadcasts/#{id}/statistics/links", params)
+      end
+    end
+  end
+end

data/lib/broadcast/resources/segments.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Segments < Base
+      def list(**params)
+        get('/api/v1/segments.json', params)
+      end
+
+      def get_segment(id, page: nil)
+        params = page ? { page: page } : {}
+        get("/api/v1/segments/#{id}.json", params)
+      end
+
+      def create(**attrs)
+        post('/api/v1/segments', { segment: attrs })
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/segments/#{id}", { segment: attrs })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/segments/#{id}")
+      end
+    end
+  end
+end

data/lib/broadcast/resources/sequences.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Sequences < Base
+      def list(**params)
+        get('/api/v1/sequences', params)
+      end
+
+      def get_sequence(id, include_steps: false)
+        params = include_steps ? { include_steps: true } : {}
+        get("/api/v1/sequences/#{id}", params)
+      end
+
+      def create(**attrs)
+        post('/api/v1/sequences', attrs)
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/sequences/#{id}", attrs)
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/sequences/#{id}")
+      end
+
+      # --- Subscriber enrollment ---
+
+      def add_subscriber(sequence_id, **attrs)
+        post("/api/v1/sequences/#{sequence_id}/add_subscriber", attrs)
+      end
+
+      def remove_subscriber(sequence_id, email:)
+        @client.request(:delete, "/api/v1/sequences/#{sequence_id}/remove_subscriber", { email: email })
+      end
+
+      def list_subscribers(sequence_id, page: 1)
+        get("/api/v1/sequences/#{sequence_id}/list_subscribers", { page: page })
+      end
+
+      # --- Steps ---
+
+      def list_steps(sequence_id)
+        get("/api/v1/sequences/#{sequence_id}/steps")
+      end
+
+      def get_step(sequence_id, step_id)
+        get("/api/v1/sequences/#{sequence_id}/steps/#{step_id}")
+      end
+
+      def create_step(sequence_id, **attrs)
+        post("/api/v1/sequences/#{sequence_id}/steps", attrs)
+      end
+
+      def update_step(sequence_id, step_id, **attrs)
+        patch("/api/v1/sequences/#{sequence_id}/steps/#{step_id}", attrs)
+      end
+
+      def move_step(sequence_id, step_id, under_id:)
+        post("/api/v1/sequences/#{sequence_id}/steps/#{step_id}/move", { under_id: under_id })
+      end
+
+      def delete_step(sequence_id, step_id)
+        @client.request(:delete, "/api/v1/sequences/#{sequence_id}/steps/#{step_id}")
+      end
+    end
+  end
+end

data/lib/broadcast/resources/subscribers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Subscribers < Base
+      def list(**params)
+        get('/api/v1/subscribers.json', params)
+      end
+
+      def find(email:)
+        get('/api/v1/subscribers/find.json', { email: email })
+      end
+
+      def create(**attrs)
+        post('/api/v1/subscribers.json', { subscriber: attrs })
+      end
+
+      def update(email, **attrs)
+        patch('/api/v1/subscribers.json', { email: email, subscriber: attrs })
+      end
+
+      def add_tags(email, tags)
+        post('/api/v1/subscribers/add_tag.json', { email: email, tags: tags })
+      end
+
+      def remove_tags(email, tags)
+        @client.request(:delete, '/api/v1/subscribers/remove_tag.json', { email: email, tags: tags })
+      end
+
+      def deactivate(email)
+        post('/api/v1/subscribers/deactivate.json', { email: email })
+      end
+
+      def activate(email)
+        post('/api/v1/subscribers/activate.json', { email: email })
+      end
+
+      def unsubscribe(email)
+        post('/api/v1/subscribers/unsubscribe.json', { email: email })
+      end
+
+      def resubscribe(email)
+        post('/api/v1/subscribers/resubscribe.json', { email: email })
+      end
+
+      def redact(email)
+        post('/api/v1/subscribers/redact.json', { email: email })
+      end
+    end
+  end
+end

data/lib/broadcast/resources/templates.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class Templates < Base
+      def list(**params)
+        get('/api/v1/templates', params)
+      end
+
+      def get_template(id)
+        get("/api/v1/templates/#{id}")
+      end
+
+      def create(**attrs)
+        post('/api/v1/templates', { template: attrs })
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/templates/#{id}", { template: attrs })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/templates/#{id}")
+      end
+    end
+  end
+end

data/lib/broadcast/resources/webhook_endpoints.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Broadcast
+  module Resources
+    class WebhookEndpoints < Base
+      def list(**params)
+        get('/api/v1/webhook_endpoints', params)
+      end
+
+      def get_endpoint(id)
+        get("/api/v1/webhook_endpoints/#{id}")
+      end
+
+      def create(**attrs)
+        post('/api/v1/webhook_endpoints', { webhook_endpoint: attrs })
+      end
+
+      def update(id, **attrs)
+        patch("/api/v1/webhook_endpoints/#{id}", { webhook_endpoint: attrs })
+      end
+
+      def delete(id)
+        @client.request(:delete, "/api/v1/webhook_endpoints/#{id}")
+      end
+
+      def test(id, event_type: 'test.webhook')
+        post("/api/v1/webhook_endpoints/#{id}/test", { event_type: event_type })
+      end
+
+      def deliveries(id, **params)
+        get("/api/v1/webhook_endpoints/#{id}/deliveries", params)
+      end
+    end
+  end
+end

data/lib/broadcast/version.rb

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

data/lib/broadcast/webhook.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+
+module Broadcast
+  module Webhook
+    TIMESTAMP_TOLERANCE = 300 # 5 minutes
+
+    module_function
+
+    def verify(payload, signature_header, timestamp_header, secret:, now: nil)
+      return false if payload.nil? || signature_header.nil? || timestamp_header.nil? || secret.nil?
+
+      timestamp = timestamp_header.to_i
+      current_time = (now || Time.now).to_i
+      return false unless timestamp_valid?(timestamp, current_time)
+
+      expected = compute_signature(payload, timestamp, secret)
+      actual = extract_signature(signature_header)
+      return false if actual.nil?
+
+      secure_compare(expected, actual)
+    end
+
+    def compute_signature(payload, timestamp, secret)
+      signed_content = "#{timestamp}.#{payload}"
+      hmac = OpenSSL::HMAC.digest('SHA256', secret, signed_content)
+      Base64.strict_encode64(hmac)
+    end
+
+    def timestamp_valid?(timestamp, current_time = Time.now.to_i)
+      (current_time - timestamp).abs <= TIMESTAMP_TOLERANCE
+    end
+
+    def extract_signature(header)
+      return nil unless header&.start_with?('v1,')
+
+      sig = header.delete_prefix('v1,')
+      return nil if sig.empty?
+
+      sig
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    end
+  end
+end

data/lib/broadcast.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative 'broadcast/version'
+require_relative 'broadcast/errors'
+require_relative 'broadcast/configuration'
+require_relative 'broadcast/client'
+require_relative 'broadcast/webhook'
+require_relative 'broadcast/resources/base'
+require_relative 'broadcast/resources/subscribers'
+require_relative 'broadcast/resources/sequences'
+require_relative 'broadcast/resources/broadcasts'
+require_relative 'broadcast/resources/segments'
+require_relative 'broadcast/resources/templates'
+require_relative 'broadcast/resources/webhook_endpoints'
+
+module Broadcast
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: broadcast-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Simon Chiu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Full API client for Broadcast. Subscribers, sequences, broadcasts, segments,
+  templates, webhooks, and transactional email. Works with any Broadcast instance.
+email:
+- simon@furvur.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/broadcast.rb
+- lib/broadcast/client.rb
+- lib/broadcast/configuration.rb
+- lib/broadcast/errors.rb
+- lib/broadcast/resources/base.rb
+- lib/broadcast/resources/broadcasts.rb
+- lib/broadcast/resources/segments.rb
+- lib/broadcast/resources/sequences.rb
+- lib/broadcast/resources/subscribers.rb
+- lib/broadcast/resources/templates.rb
+- lib/broadcast/resources/webhook_endpoints.rb
+- lib/broadcast/version.rb
+- lib/broadcast/webhook.rb
+homepage: https://github.com/send-broadcast/broadcast-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/send-broadcast/broadcast-ruby
+  source_code_uri: https://github.com/send-broadcast/broadcast-ruby
+  changelog_uri: https://github.com/send-broadcast/broadcast-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby client for the Broadcast email platform
+test_files: []