messengerr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1c93598f3e402b4a4096677f451d9b4116c2378d5fb1466405a0ba0d436802a
+  data.tar.gz: 58064c3aa1e92ec5812a301d1cf4be8191fac258abb2d1bfad65c9644ef5f9c3
+SHA512:
+  metadata.gz: c11c74416f64968164c0de51700f0e52906affcf36cd05f21965b116ed90c83db89835a5c2c0223d9d81240ebadbc235dd343fbfae0624561b3660e0396a48e8
+  data.tar.gz: 4b32107a5ffe04d44101b29818af58e5ab5cf0a637c71c355ee7c73229941cde1a08d83ab19d2b19a026d99eb4f3e422916ef9720646bead74142b17701ab5ca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daiwick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,77 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jalappeno-apps/messengerr/main/docs/assets/images/logo-lockup-dark.svg">
+    <img alt="messengerr" src="https://raw.githubusercontent.com/jalappeno-apps/messengerr/main/docs/assets/images/logo-lockup.svg" height="56">
+  </picture>
+</p>
+
+<p align="center"><b>Send templated email and SMS to a CSV contact list, safely, from your terminal.</b></p>
+
+Write one message with `{{placeholders}}`, point messengerr at a CSV, and it validates the contacts, shows you exactly what will go out, sends through your provider, and keeps a record of every result.
+
+**Documentation: [jalappeno-apps.github.io/messengerr](https://jalappeno-apps.github.io/messengerr/)**
+
+## Install
+
+Requires Ruby 3.2 or newer.
+
+```sh
+gem install messengerr
+```
+
+## Quick start
+
+```sh
+messengerr credentials setup postmark   # or clicksend; keys are verified live, then stored encrypted
+messengerr send --dry-run               # walk the wizard and preview, sending nothing
+messengerr send                         # preview, confirm, send
+```
+
+Given a CSV like
+
+```text
+name,email,plan
+Ann,ann@example.com,Pro
+Bob,bob@example.com,Team
+```
+
+and the message `Hi {{name}}, your {{plan}} invoice is ready.`, the preview shows:
+
+```text
+--- Preview (2 messages) ---
+To: ann@example.com
+Subject: Invoice for Ann
+Body: Hi Ann, your Pro invoice is ready.
+...
+```
+
+## Why it is safe to point at a real list
+
+- **Preview first.** You see the count and the first rendered messages, then confirm. `--dry-run` sends nothing.
+- **Bad data is surfaced, not sent.** Invalid contacts are listed by row. A malformed or empty placeholder aborts the run instead of going out as literal text.
+- **See the real thing.** HTML emails (`--html letter.html`) are written to a preview file you can open in a browser before you confirm. Values from the CSV are HTML-escaped.
+- **A record of every result.** Each outcome is appended to a ledger as it happens, so a crash or Ctrl-C never loses track of who was messaged.
+- **Resume without guessing.** `--resume` skips recipients already sent. Failures that might already have been delivered are marked *uncertain* and flagged before you retry.
+
+## Integrations
+
+| Integration | Delivers |
+|---|---|
+| Postmark | email |
+| ClickSend | SMS |
+
+New providers follow a small contract. See [Writing an integration](https://jalappeno-apps.github.io/messengerr/writing-an-integration.html).
+
+## Good to know
+
+messengerr sends plain-text messages (typed as one line, or multi-line from a file) and HTML email from a file, with no attachments, and does not track delivery. It adds no unsubscribe links and does not check consent: laws such as CAN-SPAM, GDPR/PECR and the TCPA are the sender's responsibility. Credentials are stored in an encrypted file under `~/.config/messengerr`, with the key beside it by default, and `gem uninstall` does not remove them. Read [Limitations](https://jalappeno-apps.github.io/messengerr/limitations.html) and [Credentials](https://jalappeno-apps.github.io/messengerr/credentials.html) before a large send.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE.md](STYLE.md).
+
+## License
+
+Released under the [MIT License](LICENSE).
+
+Maintained by [Daiwick](https://daiwick.com). Questions and enquiries: developers@daiwick.com. Bugs and feature requests: [GitHub issues](https://github.com/jalappeno-apps/messengerr/issues). Security reports: see [SECURITY.md](SECURITY.md).

data/exe/messengerr

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "messengerr"
+
+exit Messengerr::CLI.start(ARGV)

data/lib/messengerr/cli/credentials_command.rb

@@ -0,0 +1,73 @@
+module Messengerr
+  class CLI
+    # messengerr credentials setup|list|verify|delete [--purge]
+    class CredentialsCommand
+      def initialize(prompter:, credentials:)
+        @prompter = prompter
+        @credentials = credentials
+      end
+
+      def run(args)
+        case args.first
+        when "setup" then setup(args[1])
+        when "list" then list
+        when "verify" then verify(args[1])
+        when "delete" then delete(purge: args.include?("--purge"))
+        else
+          @prompter.say("Usage: messengerr credentials setup|list|verify|delete [--purge]")
+          1
+        end
+      end
+
+      private
+
+      def setup(key)
+        integration = find(key) or return 1
+        integration.setup_class.new(prompter: @prompter, credentials: @credentials).run ? 0 : 1
+      end
+
+      def list
+        @prompter.say("Registered integrations:")
+        Registry.all.each do |integration|
+          state = @credentials.configured?(integration.integration_key) ? "configured" : "not configured"
+          @prompter.say("  #{integration.integration_key} (#{integration.delivery_method}) — #{state}")
+        end
+        0
+      end
+
+      def verify(key)
+        integration = find(key) or return 1
+        creds = @credentials.read(integration.integration_key)
+        unless creds
+          @prompter.say("#{integration.integration_key} is not configured — run `messengerr credentials setup #{integration.integration_key}`")
+          return 1
+        end
+
+        integration.new(creds).verify!
+        @prompter.say("#{integration.integration_key} verified.")
+        0
+      rescue IntegrationError => e
+        @prompter.say(e.message)
+        1
+      end
+
+      def delete(purge:)
+        target = purge ? "credentials file AND master key" : "credentials file"
+        return 1 unless @prompter.confirm("Delete the #{target}?")
+
+        purge ? @credentials.purge! : @credentials.delete_file!
+        @prompter.say("Deleted.")
+        0
+      end
+
+      def find(key)
+        integration = key && Registry.find(key)
+        unless integration
+          @prompter.say("Unknown integration '#{key}'. Available: #{Registry.all.map(&:integration_key).join(', ')}")
+          return nil
+        end
+        integration
+      end
+    end
+  end
+end

data/lib/messengerr/cli/integrations_command.rb

@@ -0,0 +1,27 @@
+module Messengerr
+  class CLI
+    # messengerr integrations — registry listing by delivery method.
+    class IntegrationsCommand
+      def initialize(prompter:, credentials:)
+        @prompter = prompter
+        @credentials = credentials
+      end
+
+      def run
+        %i[email sms].each do |method|
+          @prompter.say("#{method}:")
+          integrations = Registry.by_method(method)
+          if integrations.empty?
+            @prompter.say("  (none registered)")
+          else
+            integrations.each do |integration|
+              state = @credentials.configured?(integration.integration_key) ? "configured" : "not configured"
+              @prompter.say("  #{integration.integration_key} — #{state}")
+            end
+          end
+        end
+        0
+      end
+    end
+  end
+end

data/lib/messengerr/cli/send_command.rb

@@ -0,0 +1,373 @@
+require "optparse"
+require "set"
+
+module Messengerr
+  class CLI
+    # messengerr send [flags] — interactive wizard:
+    #   delivery method → configured integration → message (with {{placeholders}})
+    #   → CSV path → map placeholders to columns → contact column → validate
+    #   (abort or drop defects) → preview → confirm → send → failures listed
+    #   → retry failed only.
+    #
+    # Flags: --dry-run, --resume LEDGER, --ledger PATH, --batch-size N,
+    #        --rate-limit N, --from ADDRESS, --message-file FILE, --html FILE
+    class SendCommand
+      SMS_SEGMENT = 160
+      # Sending options settable from flags (the integrations support more; see docs/integrations.md).
+      CLI_OPTIONS = %i[from batch_size rate_limit].freeze
+
+      def initialize(prompter:, credentials:)
+        @prompter = prompter
+        @credentials = credentials
+        @flags = { ledger: Ledger.default_path }
+      end
+
+      def run(args = [])
+        parse_flags(args)
+        if @flags[:help]
+          @prompter.say(@parser.help)
+          return 0
+        end
+        check_resume_ledger!
+        @file_message = load_message_file
+
+        method = pick_delivery_method
+        check_html_method!(method)
+        integration_class = pick_integration(method) or return 1
+        check_html_supported!(integration_class)
+        message, subject = collect_message(method)
+        source = load_csv or return 1
+        mapping = map_placeholders(message, subject, source)
+        contact_column = pick_contact_column(method, source)
+        outcome = validate_recipients(source, contact_column, method) or return 1
+        deliveries = preview_and_confirm(outcome[:valid], message, subject, mapping, method) or return 1
+
+        send_and_report(integration_class, deliveries, outcome[:defects])
+      end
+
+      private
+
+      # Bad flags are user errors, not crashes: they surface as Messengerr::Error
+      # (printed as "messengerr: ..." with exit 1) before any prompt appears.
+      def parse_flags(args)
+        @parser = build_parser
+        extra = @parser.parse(args)
+        raise Error, "unexpected argument: #{extra.join(' ')} (see `messengerr send --help`)" unless extra.empty?
+        raise Error, "use either --html or --message-file, not both (see `messengerr send --help`)" if @flags[:html] && @flags[:message_file]
+      rescue OptionParser::ParseError => e
+        raise Error, "#{e.message} (see `messengerr send --help`)"
+      end
+
+      def build_parser
+        OptionParser.new do |opts|
+          opts.banner = "Usage: messengerr send [flags]"
+          opts.on("--dry-run", "Preview the rendered messages; send nothing") { @flags[:dry_run] = true }
+          opts.on("--resume LEDGER", "Skip recipients already sent in this ledger (row + contact)") do |v|
+            @flags[:resume] = v
+            @flags[:ledger] = v
+          end
+          opts.on("--ledger PATH", "Where to record results (default: ./messengerr-ledger-<time>.jsonl)") { |v| @flags[:ledger] = v }
+          opts.on("--batch-size N", Integer, "Messages per batch") { |v| @flags[:batch_size] = positive(v) }
+          opts.on("--rate-limit N", Integer, "Batches per second") { |v| @flags[:rate_limit] = positive(v) }
+          opts.on("--from ADDRESS", "Override the sender address/ID") { |v| @flags[:from] = v }
+          opts.on("--message-file FILE", "Read a multi-line plain-text message from FILE instead of typing one line") { |v| @flags[:message_file] = v }
+          opts.on("--html FILE", "Send FILE as an HTML email (email only; HTML only, no text version)") { |v| @flags[:html] = v }
+          opts.on("-h", "--help", "Show this help") { @flags[:help] = true }
+        end
+      end
+
+      def positive(value)
+        raise OptionParser::InvalidArgument, "#{value} (must be a positive integer)" unless value.positive?
+
+        value
+      end
+
+      # A mistyped --resume path must not silently mean "nothing sent yet".
+      def check_resume_ledger!
+        return unless @flags[:resume]
+        return if File.file?(@flags[:resume])
+
+        raise Error, "resume ledger not found: #{@flags[:resume]}"
+      end
+
+      # The message from --html / --message-file, normalised, or nil when the
+      # message will be typed. Problems surface before any prompt.
+      def load_message_file
+        path = @flags[:html] || @flags[:message_file]
+        return nil unless path
+
+        expanded = File.expand_path(path)
+        raise Error, "message file not found: #{path}" unless File.file?(expanded)
+
+        text = File.read(expanded, encoding: "bom|utf-8")
+        raise Error, "message file is not valid UTF-8: #{path}" unless text.valid_encoding?
+
+        text = text.gsub("\r\n", "\n").rstrip
+        raise Error, "message file is empty: #{path}" if text.empty?
+
+        text
+      rescue SystemCallError => e
+        raise Error, "cannot read message file #{path}: #{e.message}"
+      end
+
+      def check_html_method!(method)
+        raise Error, "--html is only for email; SMS messages are plain text (use --message-file)" if @flags[:html] && method != :email
+      end
+
+      def check_html_supported!(integration_class)
+        return unless @flags[:html]
+        return if integration_class.formats.include?(:html)
+
+        raise Error, "#{integration_class.integration_key} can't send HTML email"
+      end
+
+      def message_format = @flags[:html] ? :html : :text
+
+      def pick_delivery_method
+        @prompter.choose("Delivery method:", %w[email sms]).to_sym
+      end
+
+      def pick_integration(method)
+        integrations = Registry.configured_by_method(method, @credentials)
+        if integrations.empty?
+          @prompter.say("No #{method} integrations are configured.")
+          @prompter.say("Run `messengerr credentials setup <name>` first.")
+          return nil
+        end
+
+        return integrations.first if integrations.length == 1
+
+        keys = integrations.map(&:integration_key)
+        chosen = @prompter.choose("Which #{method} integration?", keys)
+        integrations[keys.index(chosen)]
+      end
+
+      def collect_message(method)
+        message = @file_message
+        if message
+          @prompter.say("Message: #{message.lines.length} line(s) from #{@flags[:html] || @flags[:message_file]}")
+        else
+          message = @prompter.ask("Message (use {{column}} placeholders):")
+        end
+        subject = ask_subject if method == :email
+        [ message, subject ]
+      end
+
+      # Email needs a subject; re-ask now rather than failing after the wizard.
+      def ask_subject
+        loop do
+          subject = @prompter.ask("Subject ({{placeholders}} allowed):")
+          return subject unless subject.strip.empty?
+
+          @prompter.say("A subject is required for email.")
+        end
+      end
+
+      def load_csv
+        path = @prompter.ask("Path to CSV file:")
+        source = CsvSource.from(path)
+        @prompter.say("Columns: #{source.headers.join(', ')}")
+        source
+      rescue Error => e
+        @prompter.say(e.message)
+        nil
+      end
+
+      # Placeholders in the subject are mapped just like body placeholders.
+      def map_placeholders(message, subject, source)
+        placeholders = Placeholder.extract(message) + Placeholder.extract(subject)
+        placeholders.uniq.to_h do |placeholder|
+          column = @prompter.choose("Map {{#{placeholder}}} to column:", source.headers)
+          [ placeholder, column ]
+        end
+      end
+
+      def pick_contact_column(method, source)
+        label = { email: "email address", sms: "phone number" }[method]
+        @prompter.choose("Which column holds the #{label}?", source.headers)
+      end
+
+      def validate_recipients(source, contact_column, method)
+        outcome = ContactValidator.validate(source.rows, contact_column, method)
+
+        if outcome[:defects].any?
+          @prompter.say("#{outcome[:defects].length} contact(s) have defects:")
+          outcome[:defects].each do |defect|
+            @prompter.say("  row #{defect.row_number}: #{defect.value.inspect} — #{defect.reason}")
+          end
+          unless @prompter.confirm("Drop these contacts and continue? (n = abort to fix)")
+            @prompter.say("Aborted. Fix the CSV and try again.")
+            return nil
+          end
+        end
+
+        if outcome[:valid].empty?
+          @prompter.say("No valid contacts to send to — aborting.")
+          return nil
+        end
+
+        outcome
+      end
+
+      # H1 guardrail: show what will actually go out before anything is sent.
+      def preview_and_confirm(recipients, message, subject, mapping, method)
+        deliveries = recipients.map do |recipient|
+          Delivery.new(
+            recipient:,
+            body: Renderer.render(message, recipient.row, mapping, escape: message_format == :html),
+            subject: subject && Renderer.render(subject, recipient.row, mapping),
+            format: message_format
+          )
+        rescue RenderError => e
+          @prompter.say("row #{recipient.row_number}: #{e.message}")
+          @prompter.say("Aborted — fix the CSV or mapping and try again.")
+          return nil
+        end
+
+        deliveries = resume_filter(deliveries) or return nil
+
+        @prompter.say("--- Preview (#{deliveries.length} message#{'s' if deliveries.length != 1}) ---")
+        deliveries.first(3).each do |d|
+          @prompter.say("To: #{d.recipient.contact}")
+          @prompter.say("Subject: #{d.subject}") if d.subject
+          say_body(d)
+          @prompter.say("   (#{sms_segments(d.body)} SMS segment(s))") if method == :sms
+          @prompter.say("...")
+        end
+        write_html_preview(deliveries.first) if message_format == :html
+
+        return deliveries if @flags[:dry_run] || @prompter.confirm("Send #{deliveries.length} message(s)?")
+
+        @prompter.say("Aborted — nothing was sent.")
+        nil
+      end
+
+      # Multi-line text is indented under "Body:"; HTML is never dumped to the terminal.
+      def say_body(delivery)
+        if delivery.html?
+          @prompter.say("Body: HTML, #{delivery.body.length} characters")
+        elsif delivery.body.include?("\n")
+          @prompter.say("Body:")
+          delivery.body.each_line { |line| @prompter.say("  #{line.chomp}") }
+        else
+          @prompter.say("Body: #{delivery.body}")
+        end
+      end
+
+      # Lets the user open the first rendered message in a browser before confirming.
+      def write_html_preview(delivery)
+        path = File.join(Dir.pwd, "messengerr-preview.html")
+        File.write(path, delivery.body, mode: "w", perm: 0o600)
+        @prompter.say("HTML preview of the first message: #{path}")
+      rescue SystemCallError => e
+        @prompter.say("(could not write the HTML preview: #{e.message})")
+      end
+
+      def resume_filter(deliveries)
+        return deliveries unless @flags[:resume]
+
+        warn_uncertain(deliveries)
+        sent = Ledger.sent_recipients(@flags[:resume]).to_set
+        skipped = deliveries.count { |d| sent.include?(recipient_key(d)) }
+        remaining = deliveries.reject { |d| sent.include?(recipient_key(d)) }
+        @prompter.say("Resuming: #{skipped} already sent, #{remaining.length} remaining.")
+        if remaining.empty?
+          @prompter.say("Nothing left to send.")
+          return nil
+        end
+        remaining
+      end
+
+      # How the ledger identifies a recipient: row + contact, so repeated
+      # contacts are tracked per row.
+      def recipient_key(delivery)
+        [ delivery.recipient.row_number, delivery.recipient.contact ]
+      end
+
+      # Earlier attempts that timed out etc. may have been delivered; --resume
+      # will send to them again, so say so before the confirmation.
+      def warn_uncertain(deliveries)
+        uncertain = Ledger.uncertain_recipients(@flags[:resume]).to_set
+        at_risk = deliveries.map { |d| recipient_key(d) }.select { |key| uncertain.include?(key) }.map(&:last)
+        return if at_risk.empty?
+
+        @prompter.say("Warning: #{at_risk.length} contact(s) had an earlier attempt with an unknown outcome " \
+                      "and will be sent again — they may receive duplicates:")
+        at_risk.first(10).each { |contact| @prompter.say("  #{contact}") }
+        @prompter.say("  ...and #{at_risk.length - 10} more") if at_risk.length > 10
+      end
+
+      def send_and_report(integration_class, deliveries, defects)
+        integration = integration_class.new(@credentials.read(integration_class.integration_key))
+        options = build_options(integration_class)
+        ledger = Ledger.new(@flags[:ledger])
+        sender = Sender.new(integration, options:, ledger:)
+
+        if @flags[:dry_run]
+          @prompter.say("Dry run — nothing sent. Ledger skipped.")
+          return 0
+        end
+
+        ledger.verify_writable!
+        results = deliver_all(sender, deliveries) or return 130
+
+        loop do
+          failures = results.reject(&:sent?)
+          break if failures.empty?
+
+          list_failures(failures)
+          break if sender.halted_reason
+          break unless retry_confirmed?(failures)
+
+          retrying = deliveries.select { |d| failures.any? { |f| f.recipient == d.recipient } }
+          retried = deliver_all(sender, retrying) or return 130
+          results = results.select(&:sent?) + retried
+        end
+
+        @prompter.say("Stopped early: #{sender.halted_reason}") if sender.halted_reason
+        @prompter.say("Ledger written to #{@flags[:ledger]}")
+        report = Report.new(results:, dropped: defects)
+        @prompter.say("Done — #{report.summary}")
+        report.ok? ? 0 : 1
+      end
+
+      # → [Result], or nil if the user hit Ctrl-C (the ledger already holds
+      # everything that was delivered; unreported sends are marked uncertain).
+      def deliver_all(sender, deliveries)
+        sender.deliver(deliveries)
+      rescue Interrupt
+        @prompter.say("\nInterrupted. Ledger: #{@flags[:ledger]}")
+        @prompter.say("Resume later with: messengerr send --resume #{@flags[:ledger]}")
+        nil
+      end
+
+      def list_failures(failures)
+        @prompter.say("#{failures.length} send(s) failed:")
+        failures.each do |result|
+          line = "  row #{result.recipient.row_number} (#{result.recipient.contact}): #{result.reason}"
+          line += " [uncertain — may already be delivered]" if result.uncertain
+          @prompter.say(line)
+        end
+      end
+
+      def retry_confirmed?(failures)
+        if failures.any?(&:uncertain)
+          @prompter.say("Warning: some failures are uncertain — retrying may send duplicates.")
+        end
+        @prompter.confirm("Retry failed sends?")
+      end
+
+      def build_options(integration_class)
+        options = integration_class.options_class.new
+        CLI_OPTIONS.each do |key|
+          options.public_send("#{key}=", @flags[key]) if @flags[key] && options.respond_to?("#{key}=")
+        end
+        options
+      end
+
+      def sms_segments(body)
+        body.length <= SMS_SEGMENT ? 1 : (body.length / 153.0).ceil
+      end
+    end
+  end
+end

data/lib/messengerr/cli.rb

@@ -0,0 +1,50 @@
+require "optparse"
+
+module Messengerr
+  class CLI
+    BANNER = <<~TEXT
+      Usage: messengerr <command>
+
+      Commands:
+        credentials  Manage integration credentials (setup|list|verify|delete)
+        send         Send a message to a CSV contact list (see `send --help`)
+        integrations List registered integrations
+    TEXT
+
+    def self.start(argv, prompter: Prompter.new, credentials: Credentials.new, out: $stdout)
+      new(prompter:, credentials:, out:).start(argv)
+    end
+
+    def initialize(prompter:, credentials:, out: $stdout)
+      @prompter = prompter
+      @credentials = credentials
+      @out = out
+    end
+
+    def start(argv)
+      command = argv.first
+
+      case command
+      when "credentials"
+        CLI::CredentialsCommand.new(prompter: @prompter, credentials: @credentials).run(argv[1..])
+      when "send"
+        CLI::SendCommand.new(prompter: @prompter, credentials: @credentials).run(argv[1..])
+      when "integrations"
+        CLI::IntegrationsCommand.new(prompter: @prompter, credentials: @credentials).run
+      when "-h", "--help", nil
+        @out.puts BANNER
+        0
+      when "-v", "--version"
+        @out.puts Messengerr::VERSION
+        0
+      else
+        @out.puts "messengerr: unknown command '#{command}'"
+        @out.puts BANNER
+        1
+      end
+    rescue Error => e
+      @out.puts "messengerr: #{e.message}"
+      1
+    end
+  end
+end

data/lib/messengerr/contact_validator.rb

@@ -0,0 +1,48 @@
+require "uri"
+require "phonelib"
+
+module Messengerr
+  # Validates contact values for a delivery method. Returns valid Recipients
+  # and a list of defects the user can inspect, then drop or abort on.
+  # Repeated contacts are deliberately kept: one row = one message.
+  module ContactValidator
+    Defect = Data.define(:row_number, :value, :reason)
+
+    def self.validate(rows, contact_column, delivery_method)
+      Phonelib.default_country ||= ENV["MESSENGERR_DEFAULT_COUNTRY"] if delivery_method == :sms
+
+      valid = []
+      defects = []
+
+      rows.each_with_index do |row, index|
+        row_number = index + 2 # header is line 1
+        case check(row[contact_column], delivery_method)
+        in [ :ok, normalized ]
+          valid << Recipient.new(contact: normalized, row:, row_number:)
+        in [ :defect, reason ]
+          defects << Defect.new(row_number:, value: row[contact_column], reason:)
+        end
+      end
+      { valid:, defects: }
+    end
+
+    def self.check(value, delivery_method)
+      return [ :defect, "empty value" ] if value.nil? || value.strip.empty?
+
+      value = value.strip
+      case delivery_method
+      when :email
+        if value.match?(URI::MailTo::EMAIL_REGEXP) && value.split("@", 2).last.include?(".")
+          [ :ok, value.downcase ]
+        else
+          [ :defect, "invalid email address" ]
+        end
+      when :sms
+        phone = Phonelib.parse(value)
+        phone.valid? ? [ :ok, phone.e164 ] : [ :defect, "invalid phone number" ]
+      else
+        raise Error, "unknown delivery method: #{delivery_method}"
+      end
+    end
+  end
+end