messengerr 0.1.0

data/lib/messengerr/credentials.rb

@@ -0,0 +1,117 @@
+require "yaml"
+require "fileutils"
+require "securerandom"
+
+module Messengerr
+  # Encrypted YAML store for integration credentials (Rails-credentials-style).
+  #
+  # Threat model: the encrypted file protects credentials only when the master
+  # key is kept separate from it. Set MESSENGERR_MASTER_KEY (hex, 64 chars) to
+  # keep the key out of the filesystem entirely. Otherwise a master.key file
+  # (mode 600, dir 700) is generated next to the credentials file — equivalent
+  # in practice to a mode-600 plaintext file, protecting mainly against the
+  # .enc file leaking on its own (backups, VCS, shared systems).
+  class Credentials
+    def initialize(credentials_path: Paths.credentials_file, key_path: Paths.master_key_file)
+      @credentials_path = credentials_path
+      @key_path = key_path
+    end
+
+    def read(integration_key)
+      data.fetch("integrations", {}).fetch(integration_key.to_s, nil)
+    end
+
+    def write(integration_key, values)
+      merged = data
+      merged["integrations"] ||= {}
+      merged["integrations"][integration_key.to_s] = values.transform_keys(&:to_s)
+      persist(merged)
+    end
+
+    def configured?(integration_key)
+      !read(integration_key).nil?
+    end
+
+    def keys
+      data.fetch("integrations", {}).keys
+    end
+
+    def exists?
+      File.exist?(@credentials_path)
+    end
+
+    def delete_file!
+      FileUtils.rm_f(@credentials_path)
+    end
+
+    def purge!
+      delete_file!
+      FileUtils.rm_f(@key_path)
+    end
+
+    private
+
+    def data
+      return {} unless exists?
+
+      YAML.safe_load(Crypto.decrypt(File.read(@credentials_path), master_key(read_only: true))) || {}
+    rescue Psych::SyntaxError
+      raise CredentialsError, "credentials file decrypted to invalid YAML — it may be corrupted"
+    end
+
+    def persist(hash)
+      dir = File.dirname(@credentials_path)
+      # mkdir_p creates missing directories 0700; directories that already
+      # exist (e.g. a shared MESSENGERR_CONFIG_DIR) are never chmod-ed.
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      write_secret(@credentials_path, Crypto.encrypt(YAML.dump(hash), master_key))
+    rescue Errno::EACCES, Errno::EROFS
+      raise CredentialsError,
+            "cannot write #{@credentials_path} — check permissions on #{dir}"
+    end
+
+    def master_key(read_only: false)
+      env_key = ENV["MESSENGERR_MASTER_KEY"]
+      return env_master_key(env_key) if env_key
+
+      if File.exist?(@key_path)
+        hex = File.read(@key_path).strip
+        unless hex.match?(/\A[0-9a-fA-F]{64}\z/)
+          raise CredentialsError, "#{@key_path} is malformed — run `messengerr credentials delete --purge` to reset"
+        end
+        [ hex ].pack("H*")
+      elsif read_only
+        raise CredentialsError,
+              "credentials exist but no master key is available — set MESSENGERR_MASTER_KEY " \
+              "or run `messengerr credentials delete` to reset"
+      else
+        key = SecureRandom.random_bytes(32)
+        write_secret(@key_path, key.unpack1("H*"))
+        key
+      end
+    end
+
+    # An explicitly set key must be valid: an empty or malformed value is a
+    # misconfiguration, never a reason to fall back to a key file silently.
+    def env_master_key(value)
+      hex = value.strip
+      unless hex.match?(/\A\h{64}\z/)
+        raise CredentialsError,
+              "MESSENGERR_MASTER_KEY must be 64 hex characters (32 bytes)" \
+              "#{' — it is set but empty' if hex.empty?}; unset it to use the key file instead"
+      end
+      [ hex ].pack("H*")
+    end
+
+    # Create files 0600 from birth and write atomically (temp + rename) so a
+    # crash never leaves a truncated credentials file.
+    def write_secret(path, contents)
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+
+      tmp = File.join(dir, ".#{File.basename(path)}.tmp")
+      File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(contents) }
+      File.rename(tmp, path)
+    end
+  end
+end

data/lib/messengerr/crypto.rb

@@ -0,0 +1,39 @@
+require "openssl"
+require "base64"
+
+module Messengerr
+  # AES-256-GCM encryption. Encrypted payload is base64(iv + ciphertext + tag).
+  module Crypto
+    CIPHER = "aes-256-gcm"
+    IV_LENGTH = 12
+    TAG_LENGTH = 16
+
+    def self.encrypt(plaintext, key)
+      cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+      cipher.key = key
+      iv = cipher.random_iv
+      ciphertext = cipher.update(plaintext) + cipher.final
+      Base64.strict_encode64(iv + ciphertext + cipher.auth_tag)
+    end
+
+    def self.decrypt(payload, key)
+      data = Base64.strict_decode64(payload)
+      if data.bytesize < IV_LENGTH + TAG_LENGTH + 1
+        raise CredentialsError, "credentials file is truncated or malformed"
+      end
+      iv, rest = data[0, IV_LENGTH], data[IV_LENGTH..]
+      ciphertext, tag = rest[0...-TAG_LENGTH], rest[-TAG_LENGTH..]
+
+      cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+      cipher.key = key
+      cipher.iv = iv
+      cipher.auth_tag = tag
+      cipher.auth_data = ""
+      cipher.update(ciphertext) + cipher.final
+    rescue CredentialsError
+      raise
+    rescue StandardError
+      raise CredentialsError, "credentials could not be decrypted — master key is missing or incorrect"
+    end
+  end
+end

data/lib/messengerr/csv_source.rb

@@ -0,0 +1,31 @@
+require "csv"
+
+module Messengerr
+  # Local CSV file → headers + string-keyed row hashes.
+  class CsvSource
+    attr_reader :headers, :rows
+
+    def self.from(path)
+      expanded = File.expand_path(path)
+      raise Error, "CSV file not found: #{path}" unless File.file?(expanded)
+
+      table = CSV.read(expanded, headers: true, encoding: "bom|utf-8")
+      headers = table.headers.compact
+      raise Error, "CSV has no header row: #{path}" if headers.empty?
+
+      duplicates = headers.tally.select { |_, count| count > 1 }.keys
+      unless duplicates.empty?
+        raise Error, "CSV has duplicate headers: #{duplicates.join(', ')}"
+      end
+
+      new(headers: table.headers, rows: table.map(&:to_h))
+    rescue CSV::MalformedCSVError, Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError => e
+      raise Error, "could not parse CSV #{path}: #{e.message}"
+    end
+
+    def initialize(headers:, rows:)
+      @headers = headers
+      @rows = rows
+    end
+  end
+end

data/lib/messengerr/delivery.rb

@@ -0,0 +1,15 @@
+module Messengerr
+  # One fully-rendered outbound message: who it goes to, the body, and an
+  # optional per-recipient subject (email). `format` says how to read `body`:
+  # :text (the default) or :html. Only integrations that declare :html in
+  # `.formats` are ever handed an :html delivery.
+  Delivery = Data.define(:recipient, :body, :subject, :format) do
+    def initialize(recipient:, body:, subject:, format: :text)
+      raise ArgumentError, "unknown delivery format: #{format.inspect}" unless %i[text html].include?(format)
+
+      super
+    end
+
+    def html? = format == :html
+  end
+end

data/lib/messengerr/errors.rb

@@ -0,0 +1,10 @@
+module Messengerr
+  class Error < StandardError; end
+  class CredentialsError < Error; end
+  class IntegrationError < Error; end
+  # The provider may have accepted the request (timeout after sending, 5xx,
+  # unreadable response). Retrying can duplicate the message.
+  class UncertainError < IntegrationError; end
+  class ValidationError < Error; end
+  class RenderError < Error; end
+end

data/lib/messengerr/integrations/base.rb

@@ -0,0 +1,59 @@
+module Messengerr
+  module Integrations
+    # Contract every delivery integration implements. Instances are built with
+    # the integration's decrypted credentials hash.
+    class Base
+      # :email or :sms — declared by the integration, not encoded in the namespace.
+      def self.delivery_method
+        raise NotImplementedError, "#{name} must declare .delivery_method"
+      end
+
+      # Body formats this integration can send: :text, and :html if it
+      # delivers HTML. The CLI refuses --html for an integration that doesn't
+      # list :html, so markup is never sent as plain text by mistake.
+      def self.formats
+        [ :text ]
+      end
+
+      def self.integration_key
+        name.split("::").last.downcase.to_sym
+      end
+
+      # Parallel namespaces resolved by convention; override to wire explicitly.
+      def self.setup_class
+        Messengerr::Setups.const_get(class_name, false)
+      end
+
+      def self.options_class
+        Messengerr::SendingOptions.const_get(class_name, false)
+      end
+
+      def self.class_name
+        name.split("::").last
+      end
+
+      def self.inherited(subclass)
+        super
+        Registry.register(subclass) if subclass.name
+      end
+
+      def initialize(credentials)
+        @credentials = credentials
+      end
+
+      # Send each Delivery (recipient + rendered body + optional subject).
+      # → Array of Result, one per delivery — exactly one per recipient.
+      # Integrations that send one by one should `yield` each Result as it lands
+      # (optional block) so the ledger survives a crash mid-batch. Mark a failure
+      # `uncertain: true` unless the provider definitely rejected it.
+      def send_batch(deliveries, options)
+        raise NotImplementedError, "#{self.class.name} must implement #send_batch"
+      end
+
+      # Cheap live call proving the credentials work; raise IntegrationError on failure.
+      def verify!
+        raise NotImplementedError, "#{self.class.name} must implement #verify!"
+      end
+    end
+  end
+end

data/lib/messengerr/integrations/clicksend.rb

@@ -0,0 +1,92 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Messengerr
+  module Integrations
+    # ClickSend — SMS delivery via the v3 REST API using basic auth
+    # (username + api_key). No SDK dependency.
+    class ClickSend < Base
+      API_URL = "https://rest.clicksend.com/v3"
+
+      def self.delivery_method
+        :sms
+      end
+
+      def send_batch(deliveries, options)
+        body = {
+          messages: deliveries.map { |delivery|
+            { to: delivery.recipient.contact, body: delivery.body }.tap do |m|
+              m[:from] = options.from || @credentials["from"] if options.from || @credentials["from"]
+              m[:schedule] = options.schedule if options.schedule
+            end
+          }
+        }
+        response = post("/sms/send", body)
+        results = response.dig("data", "messages") || []
+        deliveries.each_with_index.map do |delivery, index|
+          entry = results[index]
+          if entry && %w[SUCCESS QUEUED].include?(entry["status"])
+            Result.new(recipient: delivery.recipient, status: :sent, provider_id: entry["message_id"])
+          else
+            Result.new(recipient: delivery.recipient, status: :failed,
+                       reason: entry ? entry["status"] : "no status returned",
+                       uncertain: entry.nil?)
+          end
+        end
+      rescue IntegrationError => e
+        uncertain = e.is_a?(UncertainError)
+        deliveries.map { |d| Result.new(recipient: d.recipient, status: :failed, reason: e.message, uncertain:) }
+      end
+
+      def verify!
+        response = request(:get, "/account")
+        raise IntegrationError, "ClickSend verification failed (#{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+        true
+      rescue IntegrationError
+        raise
+      rescue StandardError => e
+        raise IntegrationError, "ClickSend unreachable: #{e.message}"
+      end
+
+      private
+
+      def post(path, payload)
+        response = request(:post, path, payload)
+        unless response.is_a?(Net::HTTPSuccess)
+          # 4xx = definitively rejected. 5xx (incl. gateway 502/504) can happen
+          # after the batch was queued, so the outcome is unknown.
+          error = response.code.to_i >= 500 ? UncertainError : IntegrationError
+          raise error, "ClickSend rejected the request (#{response.code}): #{response.body.to_s[0, 200]}"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise UncertainError, "ClickSend returned an unreadable response (#{response.code}) — status unknown"
+      end
+
+      def request(verb, path, payload = nil)
+        uri = URI("#{API_URL}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.open_timeout = 5
+        http.read_timeout = 10
+
+        request = verb == :get ? Net::HTTP::Get.new(uri) : Net::HTTP::Post.new(uri)
+        request.basic_auth(@credentials["username"], @credentials["api_key"])
+        if payload
+          request["Content-Type"] = "application/json"
+          request.body = JSON.dump(payload)
+        end
+        http.request(request)
+      rescue Net::OpenTimeout, Errno::ECONNREFUSED, SocketError, OpenSSL::SSL::SSLError => e
+        # Failed before the request reached ClickSend: definitely not sent.
+        raise IntegrationError, "ClickSend unreachable: #{e.message}"
+      rescue Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET, Errno::EPIPE, EOFError => e
+        # The request may have been processed before the connection died.
+        raise UncertainError, "ClickSend connection lost mid-request (status unknown): #{e.message}"
+      end
+    end
+  end
+end

data/lib/messengerr/integrations/postmark.rb

@@ -0,0 +1,77 @@
+module Messengerr
+  module Integrations
+    # Postmark — email delivery via the postmark gem (lazy-loaded).
+    class Postmark < Base
+      def self.delivery_method
+        :email
+      end
+
+      def self.formats
+        [ :text, :html ]
+      end
+
+      def send_batch(deliveries, options)
+        deliveries.map do |delivery|
+          deliver_one(delivery, options).tap { |result| yield result if block_given? }
+        end
+      end
+
+      def verify!
+        client.server_info
+        true
+      rescue LoadError
+        raise
+      rescue StandardError => e
+        raise IntegrationError, "Postmark verification failed: #{e.message}"
+      end
+
+      private
+
+      def deliver_one(delivery, options)
+        subject = delivery.subject || options.subject
+        if subject.to_s.strip.empty?
+          return Result.new(recipient: delivery.recipient, status: :failed, reason: "subject is required for email sends")
+        end
+
+        response = client.deliver(
+          {
+            from: options.from || @credentials["from"],
+            to: delivery.recipient.contact,
+            subject:,
+            **body_params(delivery),
+            message_stream: options.message_stream,
+            tag: options.tag,
+            track_opens: options.track_opens
+          }.compact
+        )
+        Result.new(recipient: delivery.recipient, status: :sent, provider_id: response[:message_id])
+      rescue StandardError => e
+        Result.new(recipient: delivery.recipient, status: :failed, reason: e.message,
+                   uncertain: !definitely_rejected?(e))
+      end
+
+      # Exactly one body: HTML mail is HTML only, text mail is text only.
+      def body_params(delivery)
+        delivery.html? ? { html_body: delivery.body } : { text_body: delivery.body }
+      end
+
+      # Only a 4xx from the API proves the message was not accepted. Timeouts,
+      # connection errors, 5xx and anything unrecognised may have gone through.
+      def definitely_rejected?(error)
+        defined?(::Postmark::HttpServerError) &&
+          error.is_a?(::Postmark::HttpServerError) &&
+          (400..499).cover?(error.status_code)
+      end
+
+      def client
+        @client ||= begin
+          require "postmark"
+          ::Postmark::ApiClient.new(@credentials["server_token"])
+        rescue LoadError
+          raise IntegrationError,
+                "the postmark integration requires the 'postmark' gem — add it to your Gemfile or `gem install postmark`"
+        end
+      end
+    end
+  end
+end

data/lib/messengerr/integrations.rb

@@ -0,0 +1,5 @@
+module Messengerr
+  # Namespace for delivery integrations (Postmark, ClickSend, community gems).
+  module Integrations
+  end
+end

data/lib/messengerr/ledger.rb

@@ -0,0 +1,78 @@
+require "json"
+require "fileutils"
+require "time"
+
+module Messengerr
+  # Durable record of send outcomes, one JSONL line per Result, appended as
+  # each result lands so a crash mid-run loses nothing already delivered —
+  # and `--resume` can skip contacts already marked sent. It holds every
+  # contact's address/number, so it is created owner-only (0600).
+  class Ledger
+    def initialize(path)
+      @path = path
+    end
+
+    # Fail before anything is sent if the ledger can't be written.
+    def verify_writable!
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, "a", 0o600) { }
+    rescue SystemCallError, IOError => e
+      raise Error, "cannot write ledger #{@path}: #{e.message}"
+    end
+
+    def record(result)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.open(@path, "a", 0o600) do |file|
+        file.puts(JSON.dump(
+          row_number: result.recipient.row_number,
+          contact: result.recipient.contact,
+          status: result.status,
+          reason: result.reason,
+          provider_id: result.provider_id,
+          uncertain: result.uncertain,
+          sent_at: Time.now.utc.iso8601
+        ))
+        file.flush
+      end
+    end
+
+    # Recipients already sent per this ledger — used by --resume. A recipient
+    # is [row_number, contact]: repeated contacts are separate messages, so
+    # sending row 2 to a@x.com says nothing about row 5 to the same address.
+    def self.sent_recipients(path)
+      outcomes(path).select { |_, state| state == :sent }.keys
+    end
+
+    # Recipients whose last attempt failed *uncertainly* and never later
+    # succeeded: they may already have received the message.
+    def self.uncertain_recipients(path)
+      outcomes(path).select { |_, state| state == :uncertain }.keys
+    end
+
+    def self.default_path
+      File.join(Dir.pwd, "messengerr-ledger-#{Time.now.utc.strftime('%Y%m%d-%H%M%S')}.jsonl")
+    end
+
+    # [row_number, contact] → :sent | :uncertain | :failed. :sent is terminal.
+    def self.outcomes(path)
+      return {} unless File.exist?(path)
+
+      File.readlines(path).each_with_object({}) do |line, states|
+        entry = JSON.parse(line)
+        next if entry["contact"].nil?
+
+        recipient = [ entry["row_number"], entry["contact"] ]
+        next if states[recipient] == :sent
+
+        states[recipient] =
+          if entry["status"] == "sent" then :sent
+          elsif entry["uncertain"] then :uncertain
+          else :failed
+          end
+      rescue JSON::ParserError
+        next # a torn final line from a crash
+      end
+    end
+    private_class_method :outcomes
+  end
+end

data/lib/messengerr/paths.rb

@@ -0,0 +1,19 @@
+module Messengerr
+  # Locations for messengerr-owned files. Credentials live in the user's
+  # config directory (~/.config/messengerr by default, overridable with
+  # MESSENGERR_CONFIG_DIR) so they survive gem upgrades.
+  module Paths
+    def self.config_dir
+      override = ENV["MESSENGERR_CONFIG_DIR"].to_s.strip
+      override.empty? ? File.join(Dir.home, ".config", "messengerr") : override
+    end
+
+    def self.credentials_file
+      File.join(config_dir, "credentials.yml.enc")
+    end
+
+    def self.master_key_file
+      File.join(config_dir, "master.key")
+    end
+  end
+end

data/lib/messengerr/placeholder.rb

@@ -0,0 +1,10 @@
+module Messengerr
+  # Extracts {{placeholder}} names from message text.
+  module Placeholder
+    PATTERN = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/
+
+    def self.extract(text)
+      text.to_s.scan(PATTERN).flatten.uniq
+    end
+  end
+end

data/lib/messengerr/prompter.rb

@@ -0,0 +1,59 @@
+require "io/console"
+
+module Messengerr
+  # Injectable stdin/stdout interaction so CLI flows are scriptable and testable.
+  class Prompter
+    def initialize(input: $stdin, output: $stdout)
+      @input = input
+      @output = output
+    end
+
+    def say(message)
+      @output.puts(message)
+    end
+
+    def ask(question)
+      @output.print("#{question} ")
+      @output.flush
+      read_line
+    end
+
+    def secret(question)
+      @output.print("#{question} ")
+      @output.flush
+      if @input.respond_to?(:noecho) && @input.tty?
+        value = @input.noecho(&:gets)&.chomp
+        @output.puts
+        value
+      else
+        read_line
+      end
+    end
+
+    def choose(question, options)
+      @output.puts(question)
+      options.each_with_index { |o, i| @output.puts("  #{i + 1}) #{o}") }
+      loop do
+        answer = ask("Choose 1-#{options.length}:")
+        index = Integer(answer, exception: false)
+        return options[index - 1] if index&.between?(1, options.length)
+
+        @output.puts("Please enter a number between 1 and #{options.length}.")
+      end
+    end
+
+    def confirm(question)
+      answer = ask("#{question} [y/n]")
+      answer.to_s.strip.downcase.start_with?("y")
+    end
+
+    private
+
+    def read_line
+      line = @input.gets
+      raise Error, "unexpected end of input" if line.nil?
+
+      line.chomp
+    end
+  end
+end

data/lib/messengerr/recipient.rb

@@ -0,0 +1,4 @@
+module Messengerr
+  # One sendable contact: normalized contact value plus its source row data.
+  Recipient = Data.define(:contact, :row, :row_number)
+end

data/lib/messengerr/registry.rb

@@ -0,0 +1,49 @@
+module Messengerr
+  # Lookup table of registered integration classes. Built-in integrations
+  # register themselves when Zeitwerk loads them; community gems call
+  # Messengerr.register_integration on load.
+  module Registry
+    @integrations = []
+
+    class << self
+      def register(integration_class)
+        raise Error, "anonymous classes can't be registered as integrations" if integration_class.name.nil?
+
+        existing = @integrations.find { |i| i.integration_key == integration_class.integration_key }
+        if existing && existing != integration_class
+          raise Error,
+                "integration key :#{integration_class.integration_key} is already taken by #{existing.name}"
+        end
+        @integrations << integration_class unless @integrations.include?(integration_class)
+      end
+
+      def all
+        ensure_loaded
+        @integrations.dup
+      end
+
+      def by_method(delivery_method)
+        all.select { |i| i.delivery_method == delivery_method.to_sym }
+      end
+
+      def find(integration_key)
+        all.find { |i| i.integration_key == integration_key.to_sym }
+      end
+
+      def configured(credentials = Credentials.new)
+        all.select { |i| credentials.configured?(i.integration_key) }
+      end
+
+      def configured_by_method(delivery_method, credentials = Credentials.new)
+        by_method(delivery_method).select { |i| credentials.configured?(i.integration_key) }
+      end
+
+      private
+
+      # Touch the built-in integration constants so Zeitwerk loads (and registers) them.
+      def ensure_loaded
+        Integrations.constants.each { |c| Integrations.const_get(c) }
+      end
+    end
+  end
+end