messengerr 0.1.0

data/lib/messengerr/renderer.rb

@@ -0,0 +1,30 @@
+require "cgi"
+
+module Messengerr
+  # Substitutes {{placeholder}} tokens with values from a CSV row, using a
+  # user-supplied mapping of placeholder name → column name. Any leftover
+  # {{ or }} after substitution is a render failure — never sent literally.
+  #
+  # With `escape: true` (HTML messages) every substituted value is HTML-escaped,
+  # so CSV data can never inject markup. The template itself is trusted.
+  module Renderer
+    def self.render(template, row, mapping, escape: false)
+      rendered = template.gsub(Placeholder::PATTERN) do
+        key = Regexp.last_match(1)
+        column = mapping[key]
+        raise RenderError, "no column mapped for placeholder {{#{key}}}" if column.nil?
+
+        value = row[column]
+        raise RenderError, "column \"#{column}\" is empty for {{#{key}}}" if value.nil? || value.strip.empty?
+
+        escape ? CGI.escapeHTML(value.strip) : value.strip
+      end
+
+      if rendered.match?(/\{\{|\}\}/)
+        raise RenderError, "unrenderable placeholder left in message: #{rendered[/\{\{[^}]*\}?\}?/]}"
+      end
+
+      rendered
+    end
+  end
+end

data/lib/messengerr/report.rb

@@ -0,0 +1,24 @@
+module Messengerr
+  # Aggregate outcome of a send run: Results plus dropped validation defects.
+  class Report
+    attr_reader :results, :dropped
+
+    def initialize(results: [], dropped: [])
+      @results = results
+      @dropped = dropped # validation defects the user chose to drop
+    end
+
+    def successes = @results.select(&:sent?)
+    def failures = @results.reject(&:sent?)
+
+    def sent_count = successes.length
+    def failed_count = failures.length
+    def dropped_count = @dropped.length
+
+    def ok? = failures.empty?
+
+    def summary
+      "sent: #{sent_count}, failed: #{failed_count}, dropped: #{dropped_count}"
+    end
+  end
+end

data/lib/messengerr/result.rb

@@ -0,0 +1,12 @@
+module Messengerr
+  # Per-recipient send outcome. `uncertain` marks failures where the provider
+  # may still have delivered (timeouts, unreadable responses) — retrying these
+  # can duplicate the message.
+  Result = Data.define(:recipient, :status, :reason, :provider_id, :uncertain) do
+    def initialize(recipient:, status:, reason: nil, provider_id: nil, uncertain: false)
+      super
+    end
+
+    def sent? = status == :sent
+  end
+end

data/lib/messengerr/sender.rb

@@ -0,0 +1,104 @@
+module Messengerr
+  # Dispatches Deliveries through an integration in batch_size slices,
+  # throttled by rate_limit. Every delivery produces exactly one Result:
+  # exceptions become failed Results, and integrations that return too few
+  # results get the gaps filled rather than silently losing contacts.
+  #
+  # Integrations that send one message at a time may yield each Result from
+  # send_batch as it lands; the Sender records those to the ledger immediately,
+  # so a crash or Ctrl-C mid-batch never loses what was already delivered.
+  class Sender
+    # Why the run stopped early, if it did (currently: the ledger became
+    # unwritable, so no further batch is sent without a record).
+    attr_reader :halted_reason
+
+    def initialize(integration, options: integration.class.options_class.new, ledger: nil)
+      @integration = integration
+      @options = options
+      @options.validate!
+      @ledger = ledger
+      @recorded = {}
+      @halted_reason = nil
+    end
+
+    # deliveries → [Result], one per delivery, in slice order.
+    def deliver(deliveries)
+      deliveries.each_slice(@options.batch_size).with_index.flat_map do |slice, index|
+        throttle if index.positive? && !@halted_reason
+        @halted_reason ? halted_results(slice) : dispatch(slice)
+      end
+    end
+
+    private
+
+    def dispatch(slice)
+      @recorded = {} # dedupe is per batch: a retry must be recorded again
+      seen = {}
+      results =
+        begin
+          returned = @integration.send_batch(slice, @options) do |result|
+            seen[key(result.recipient)] = result
+            record(result)
+          end
+          reconcile(slice, returned, seen)
+        rescue Interrupt
+          # Whatever hadn't reported back may or may not have gone out.
+          slice.each { |d| record(seen[key(d.recipient)] || failure(d, "interrupted", uncertain: true)) }
+          raise
+        rescue StandardError => e
+          failure_results(slice, seen, e)
+        end
+
+      results.each { |r| record(r) }
+      results
+    end
+
+    # One Result per delivery. Results the integration yielded survive an
+    # exception raised later in the same batch.
+    def failure_results(slice, seen, error)
+      # A plain IntegrationError means the provider definitely rejected it;
+      # anything else (timeouts, UncertainError, bugs) may have gone out.
+      uncertain = !(error.is_a?(IntegrationError) && !error.is_a?(UncertainError))
+      slice.map { |d| seen[key(d.recipient)] || failure(d, error.message, uncertain:) }
+    end
+
+    # The contract: one Result per delivery. Gaps are filled with uncertain
+    # failures rather than silently dropping contacts.
+    def reconcile(slice, returned, seen)
+      by_recipient = Array(returned).group_by { |r| key(r.recipient) }
+      slice.map do |d|
+        k = key(d.recipient)
+        by_recipient[k]&.first || seen[k] || failure(d, "integration returned no result", uncertain: true)
+      end
+    end
+
+    def failure(delivery, reason, uncertain: false)
+      Result.new(recipient: delivery.recipient, status: :failed, reason:, uncertain:)
+    end
+
+    def halted_results(slice)
+      slice.map { |d| failure(d, "not sent — #{@halted_reason}") }
+    end
+
+    def record(result)
+      return unless @ledger
+
+      k = key(result.recipient)
+      return if @recorded[k]
+
+      @ledger.record(result)
+      @recorded[k] = true
+    rescue SystemCallError, IOError => e
+      # Never crash after a send: keep the in-memory result, stop sending more.
+      @halted_reason ||= "ledger write failed (#{e.message}); stopped so no message goes unrecorded"
+    end
+
+    def key(recipient)
+      [ recipient.row_number, recipient.contact ]
+    end
+
+    def throttle
+      sleep(1.0 / @options.rate_limit)
+    end
+  end
+end

data/lib/messengerr/sending_options/base.rb

@@ -0,0 +1,45 @@
+module Messengerr
+  module SendingOptions
+    # Shared sending options every service supports. Subclasses call `option`
+    # to add their own; each class validates its values in `validate!`.
+    class Base
+      class << self
+        def option(name)
+          options << name
+          attr_accessor name
+        end
+
+        def options
+          @options ||= superclass.respond_to?(:options) ? superclass.options.dup : []
+        end
+      end
+
+      option :from
+      option :batch_size
+      option :rate_limit
+      option :metadata
+
+      def initialize(attributes = {})
+        attributes.each do |key, value|
+          public_send("#{key}=", value)
+        end
+        @batch_size ||= 50
+        @rate_limit ||= 10
+        @metadata ||= {}
+      end
+
+      def validate!
+        errors = []
+        errors << "batch_size must be a positive integer" unless batch_size.is_a?(Integer) && batch_size.positive?
+        errors << "rate_limit must be positive" unless rate_limit.is_a?(Numeric) && rate_limit.positive?
+        raise ValidationError, errors.join(", ") unless errors.empty?
+
+        true
+      end
+
+      def to_h
+        self.class.options.to_h { |name| [ name, public_send(name) ] }
+      end
+    end
+  end
+end

data/lib/messengerr/sending_options/clicksend.rb

@@ -0,0 +1,18 @@
+module Messengerr
+  module SendingOptions
+    class ClickSend < Base
+      MAX_BATCH = 1_000 # ClickSend caps /sms/send at 1000 messages per request
+
+      option :schedule
+
+      def validate!
+        super
+        if batch_size > MAX_BATCH
+          raise ValidationError, "batch_size can't exceed #{MAX_BATCH} for ClickSend"
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/messengerr/sending_options/postmark.rb

@@ -0,0 +1,12 @@
+module Messengerr
+  module SendingOptions
+    class Postmark < Base
+      # `subject` is a fallback only; the wizard supplies a (rendered) subject
+      # per Delivery, and the integration fails any delivery that has neither.
+      option :subject
+      option :message_stream
+      option :tag
+      option :track_opens
+    end
+  end
+end

data/lib/messengerr/sending_options.rb

@@ -0,0 +1,5 @@
+module Messengerr
+  # Namespace for per-integration sending option classes.
+  module SendingOptions
+  end
+end

data/lib/messengerr/setups/base.rb

@@ -0,0 +1,80 @@
+module Messengerr
+  module Setups
+    # Interactive credential setup for an integration. The subclass declares
+    # which keys it needs; this framework prompts for them, runs the
+    # integration's live verify!, and writes the values into the encrypted
+    # credentials store.
+    class Base
+      # Keys the user must supply, e.g. [:server_token]. Optional keys go in
+      # .optional_keys and may be left blank.
+      def self.required_keys
+        []
+      end
+
+      def self.optional_keys
+        []
+      end
+
+      # The integration class this setup belongs to — inferred by convention.
+      def self.integration_class
+        Messengerr::Integrations.const_get(name.split("::").last, false)
+      end
+
+      def initialize(integration_class: self.class.integration_class,
+                     prompter: Prompter.new,
+                     credentials: Credentials.new)
+        @integration_class = integration_class
+        @prompter = prompter
+        @credentials = credentials
+      end
+
+      # Returns true when credentials were verified and stored.
+      def run
+        @prompter.say("Setting up #{@integration_class.integration_key} (#{@integration_class.delivery_method}):")
+        values = collect_values
+        return false if values.nil?
+
+        if verified?(values)
+          @credentials.write(@integration_class.integration_key, values)
+          @prompter.say("#{integration_label} is configured and verified.")
+          true
+        else
+          @prompter.confirm("Try again?") ? run : false
+        end
+      end
+
+      private
+
+      def collect_values
+        values = {}
+
+        self.class.required_keys.each do |key|
+          values[key] = @prompter.secret("#{key.to_s.tr('_', ' ')}:").to_s.strip
+        end
+        if values.values.any?(&:empty?)
+          @prompter.say("All required fields must have a value — aborting.")
+          return nil
+        end
+
+        self.class.optional_keys.each do |key|
+          value = @prompter.ask("#{key.to_s.tr('_', ' ')} (optional, enter to skip):").to_s.strip
+          values[key] = value unless value.empty?
+        end
+
+        values.transform_keys(&:to_s)
+      end
+
+      def verified?(values)
+        @integration_class.new(values).verify!
+        true
+      rescue IntegrationError => e
+        @prompter.say("Verification failed: #{e.message}")
+        false
+      end
+
+      def integration_label
+        @integration_class.integration_key.to_s.capitalize
+      end
+    end
+  end
+end

data/lib/messengerr/setups/clicksend.rb

@@ -0,0 +1,13 @@
+module Messengerr
+  module Setups
+    class ClickSend < Base
+      def self.required_keys
+        [ :username, :api_key ]
+      end
+
+      def self.optional_keys
+        [ :from ]
+      end
+    end
+  end
+end

data/lib/messengerr/setups/postmark.rb

@@ -0,0 +1,9 @@
+module Messengerr
+  module Setups
+    class Postmark < Base
+      def self.required_keys
+        [ :server_token, :from ]
+      end
+    end
+  end
+end

data/lib/messengerr/setups.rb

@@ -0,0 +1,5 @@
+module Messengerr
+  # Namespace for per-integration interactive setup wizards.
+  module Setups
+  end
+end

data/lib/messengerr/version.rb

@@ -0,0 +1,3 @@
+module Messengerr
+  VERSION = "0.1.0"
+end

data/lib/messengerr.rb

@@ -0,0 +1,22 @@
+require "zeitwerk"
+require_relative "messengerr/version"
+require_relative "messengerr/errors"
+
+module Messengerr
+  class << self
+    def loader
+      @loader ||= Zeitwerk::Loader.for_gem.tap do |loader|
+        loader.inflector.inflect("cli" => "CLI", "clicksend" => "ClickSend")
+        loader.ignore("#{__dir__}/messengerr/version.rb", "#{__dir__}/messengerr/errors.rb")
+        loader.setup
+      end
+    end
+
+    # Third-party gems call this on load to register an Integrations::Base subclass.
+    def register_integration(integration_class)
+      Registry.register(integration_class)
+    end
+  end
+end
+
+Messengerr.loader

metadata

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: messengerr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daiwick
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-10-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: phonelib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: postmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.25'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+description: Interactive CLI that renders {{placeholder}} messages against a CSV contact
+  list and dispatches through pluggable services scoped by delivery method (email,
+  sms).
+email:
+- developers@daiwick.com
+executables:
+- messengerr
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/messengerr
+- lib/messengerr.rb
+- lib/messengerr/cli.rb
+- lib/messengerr/cli/credentials_command.rb
+- lib/messengerr/cli/integrations_command.rb
+- lib/messengerr/cli/send_command.rb
+- lib/messengerr/contact_validator.rb
+- lib/messengerr/credentials.rb
+- lib/messengerr/crypto.rb
+- lib/messengerr/csv_source.rb
+- lib/messengerr/delivery.rb
+- lib/messengerr/errors.rb
+- lib/messengerr/integrations.rb
+- lib/messengerr/integrations/base.rb
+- lib/messengerr/integrations/clicksend.rb
+- lib/messengerr/integrations/postmark.rb
+- lib/messengerr/ledger.rb
+- lib/messengerr/paths.rb
+- lib/messengerr/placeholder.rb
+- lib/messengerr/prompter.rb
+- lib/messengerr/recipient.rb
+- lib/messengerr/registry.rb
+- lib/messengerr/renderer.rb
+- lib/messengerr/report.rb
+- lib/messengerr/result.rb
+- lib/messengerr/sender.rb
+- lib/messengerr/sending_options.rb
+- lib/messengerr/sending_options/base.rb
+- lib/messengerr/sending_options/clicksend.rb
+- lib/messengerr/sending_options/postmark.rb
+- lib/messengerr/setups.rb
+- lib/messengerr/setups/base.rb
+- lib/messengerr/setups/clicksend.rb
+- lib/messengerr/setups/postmark.rb
+- lib/messengerr/version.rb
+homepage: https://github.com/jalappeno-apps/messengerr
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://jalappeno-apps.github.io/messengerr/
+  source_code_uri: https://github.com/jalappeno-apps/messengerr
+  bug_tracker_uri: https://github.com/jalappeno-apps/messengerr/issues
+  changelog_uri: https://github.com/jalappeno-apps/messengerr/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Send templated messages to CSV contact lists over email and SMS.
+test_files: []