broadcast-ruby 0.2.0 → 0.3.0

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/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.3.0'
 end

data/lib/broadcast/webhook.rb

@@ -7,6 +7,40 @@ module Broadcast
   module Webhook
     TIMESTAMP_TOLERANCE = 300 # 5 minutes
 
+    # Every event type a webhook endpoint can subscribe to, mirroring
+    # WebhookEndpoint::AVAILABLE_EVENT_TYPES server-side. Use these when
+    # creating an endpoint — an unknown event type is dropped silently.
+    EMAIL_EVENTS = %w[
+      email.sent email.delivered email.delivery_delayed email.complained
+      email.bounced email.opened email.clicked email.failed
+    ].freeze
+
+    SUBSCRIBER_EVENTS = %w[
+      subscriber.created subscriber.updated subscriber.deleted
+      subscriber.subscribed subscriber.unsubscribed subscriber.bounced
+      subscriber.complained
+    ].freeze
+
+    BROADCAST_EVENTS = %w[
+      broadcast.scheduled broadcast.queueing broadcast.sending broadcast.sent
+      broadcast.failed broadcast.partial_failure broadcast.aborted
+      broadcast.paused
+    ].freeze
+
+    SEQUENCE_EVENTS = %w[
+      sequence.subscriber_added sequence.subscriber_completed
+      sequence.subscriber_moved sequence.subscriber_removed
+      sequence.subscriber_paused sequence.subscriber_resumed
+      sequence.subscriber_error
+    ].freeze
+
+    # Delivery-machinery events, not content events.
+    SYSTEM_EVENTS = %w[message.attempt.exhausted test.webhook].freeze
+
+    EVENT_TYPES = (
+      EMAIL_EVENTS + SUBSCRIBER_EVENTS + BROADCAST_EVENTS + SEQUENCE_EVENTS + SYSTEM_EVENTS
+    ).freeze
+
     module_function
 
     def verify(payload, signature_header, timestamp_header, secret:, now: nil)

data/lib/broadcast.rb

@@ -2,7 +2,10 @@
 
 require_relative 'broadcast/version'
 require_relative 'broadcast/errors'
+require_relative 'broadcast/response'
 require_relative 'broadcast/configuration'
+require_relative 'broadcast/debug_logger'
+require_relative 'broadcast/connection'
 require_relative 'broadcast/client'
 require_relative 'broadcast/webhook'
 require_relative 'broadcast/resources/base'
@@ -15,6 +18,9 @@ require_relative 'broadcast/resources/webhook_endpoints'
 require_relative 'broadcast/resources/transactionals'
 require_relative 'broadcast/resources/opt_in_forms'
 require_relative 'broadcast/resources/email_servers'
+require_relative 'broadcast/resources/autopilots'
+require_relative 'broadcast/resources/discovery'
+require_relative 'broadcast/resources/migration'
 
 # ActionMailer integration — only loaded when Rails is present
 if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: broadcast-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Simon Chiu
@@ -31,23 +31,28 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
+- SDK-COVERAGE.md
 - lib/broadcast-ruby.rb
 - lib/broadcast.rb
 - lib/broadcast/client.rb
 - lib/broadcast/configuration.rb
+- lib/broadcast/connection.rb
+- lib/broadcast/debug_logger.rb
 - lib/broadcast/delivery_method.rb
 - lib/broadcast/errors.rb
 - lib/broadcast/railtie.rb
+- lib/broadcast/resources/autopilots.rb
 - lib/broadcast/resources/base.rb
 - lib/broadcast/resources/broadcasts.rb
+- lib/broadcast/resources/discovery.rb
 - lib/broadcast/resources/email_servers.rb
+- lib/broadcast/resources/migration.rb
 - lib/broadcast/resources/opt_in_forms.rb
 - lib/broadcast/resources/segments.rb
 - lib/broadcast/resources/sequences.rb
@@ -55,6 +60,7 @@ files:
 - lib/broadcast/resources/templates.rb
 - lib/broadcast/resources/transactionals.rb
 - lib/broadcast/resources/webhook_endpoints.rb
+- lib/broadcast/response.rb
 - lib/broadcast/version.rb
 - lib/broadcast/webhook.rb
 homepage: https://github.com/send-broadcast/broadcast-ruby
@@ -80,7 +86,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby client for the Broadcast email platform
 test_files: []

data/.rubocop.yml

@@ -1,50 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.2
-  NewCops: enable
-  SuggestExtensions: false
-
-Style/StringLiterals:
-  EnforcedStyle: single_quotes
-
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: single_quotes
-
-Style/Documentation:
-  Enabled: false
-
-Metrics/MethodLength:
-  Max: 25
-  Exclude:
-    - test/**/*
-
-Metrics/AbcSize:
-  Max: 35
-  Exclude:
-    - test/**/*
-
-Metrics/ClassLength:
-  Max: 200
-  Exclude:
-    - test/**/*
-
-Metrics/CyclomaticComplexity:
-  Max: 15
-
-Metrics/PerceivedComplexity:
-  Max: 15
-
-Layout/LineLength:
-  Max: 120
-
-Naming/FileName:
-  Exclude:
-    - lib/broadcast-ruby.rb
-
-Naming/MethodParameterName:
-  AllowedNames:
-    - a
-    - b
-    - id
-    - k
-    - v
-    - to