resend_robot 0.1.0

data/lib/resend_robot/html_sanitizer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module ResendRobot
+  # Sanitizes email HTML for inline rendering in the dev UI.
+  # Preserves tables/styles (needed for email layout) but strips XSS vectors:
+  # <script>, on* event handlers, javascript: URIs.
+  module HtmlSanitizer
+    class << self
+      def sanitize(html)
+        return "" if html.nil? || html.empty?
+
+        doc = Nokogiri::HTML.fragment(html)
+        doc.css("script").remove
+        doc.traverse do |node|
+          next unless node.element?
+
+          node.attributes.each_key { |attr| node.remove_attribute(attr) if attr.start_with?("on") }
+        end
+        doc.css("[href^='javascript:'], [src^='javascript:']").each do |n|
+          n.remove_attribute("href")
+          n.remove_attribute("src")
+        end
+        doc.css("a[href]").each do |a|
+          a["target"] = "_blank"
+          a["rel"] = "noopener noreferrer"
+        end
+        doc.to_html
+      end
+    end
+  end
+end

data/lib/resend_robot/shim.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Monkey-patches Resend gem classes in development so production code
+# runs unchanged against ResendRobot's local file store.
+#
+#   SHIMMED METHODS
+#
+#   Resend::Emails.send       → ResendRobot.store_outbound
+#   Resend::Batch.send        → store each email individually
+#   Resend::Emails::Receiving.get → ResendRobot.fetch_inbound
+#   Resend::Emails::Receiving::Attachments.get → stub
+#   Resend::Webhooks.verify   → no-op, return true
+#
+module ResendRobot
+  module Shim
+    class << self
+      def install!
+        unless defined?(Resend)
+          ResendRobot.configuration.resolved_logger.warn(
+            "[ResendRobot] Resend gem not loaded — shim not installed. Add `gem 'resend'` to your Gemfile."
+          )
+          return
+        end
+
+        shim_emails_send
+        shim_batch_send
+        shim_receiving_get
+        shim_attachments_get
+        shim_webhooks_verify
+
+        ResendRobot.configuration.resolved_logger.info("[ResendRobot] Shim installed — Resend API calls intercepted in dev")
+      end
+
+      private
+
+      def shim_emails_send
+        Resend::Emails.define_singleton_method(:send) do |params, options: {}|
+          ResendRobot.store_outbound(params)
+        end
+      end
+
+      def shim_batch_send
+        Resend::Batch.define_singleton_method(:send) do |params = [], options: {}|
+          results = Array(params).map { |p| ResendRobot.store_outbound(p) }
+          { data: results }
+        end
+      end
+
+      def shim_receiving_get
+        Resend::Emails::Receiving.define_singleton_method(:get) do |email_id = ""|
+          data = ResendRobot.fetch_inbound(email_id)
+          ResendRobot.configuration.resolved_logger.info("[ResendRobot] Intercepted Receiving.get(#{email_id}) → #{data ? "found" : "nil"}")
+          data
+        end
+      end
+
+      def shim_attachments_get
+        Resend::Emails::Receiving::Attachments.define_singleton_method(:get) do |params = {}|
+          ResendRobot.configuration.resolved_logger.info("[ResendRobot] Intercepted Attachments.get(#{params[:id]}) → stub")
+          { id: params[:id], email_id: params[:email_id], filename: "stub.txt", content: "" }
+        end
+      end
+
+      def shim_webhooks_verify
+        Resend::Webhooks.define_singleton_method(:verify) do |params = {}|
+          ResendRobot.configuration.resolved_logger.info("[ResendRobot] Intercepted Webhooks.verify → true (dev bypass)")
+          true
+        end
+      end
+    end
+  end
+end

data/lib/resend_robot/storage.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+require "net/http"
+require "pathname"
+
+# Resend Robot — dev-mode Resend API shim
+#
+# Intercepts outbound email (Resend::Emails.send) and stores as JSON.
+# Simulates inbound email by POSTing to the real webhook endpoint.
+# Production code runs unchanged — same pipeline in dev and prod.
+#
+#   OUTBOUND FLOW
+#
+#   Mailer.deliver!
+#     → Resend::Mailer#deliver!
+#       → Resend::Emails.send (shimmed)
+#         → ResendRobot.store_outbound
+#           → tmp/resend_robot/outbound/{timestamp}_{id}.json
+#
+#   INBOUND FLOW
+#
+#   ResendRobot.simulate_inbound(from:, to:, subject:, body:)
+#     → store_inbound (JSON to tmp/resend_robot/inbound/)
+#     → POST /webhooks/resend { type: "email.received" }
+#       → WebhooksController (UNCHANGED)
+#         → Receiving.get (shimmed → returns stored JSON)
+#         → handle_inbound_email (PRODUCTION CODE)
+#
+module ResendRobot
+  class Storage
+    OUTBOUND_DIR = "outbound"
+    INBOUND_DIR  = "inbound"
+
+    attr_reader :config
+    attr_writer :base_dir  # Override for tests
+
+    def initialize(config)
+      @config = config
+      @base_dir = nil
+    end
+
+    # Store an outbound email. Called by the shim replacing Resend::Emails.send.
+    # Returns a hash matching Resend API response format (symbol keys).
+    def store_outbound(params)
+      ensure_dir(outbound_dir)
+      id = "rl_#{SecureRandom.hex(8)}"
+      timestamp = Time.now.strftime("%Y%m%d_%H%M%S_%6N")
+
+      email_data = {
+        id: id,
+        sent_at: Time.now.iso8601,
+        from: params[:from],
+        to: Array(params[:to]),
+        cc: params[:cc],
+        bcc: params[:bcc],
+        reply_to: Array(params[:reply_to]),
+        subject: params[:subject],
+        html: params[:html],
+        text: params[:text],
+        tags: params[:tags],
+        headers: params[:headers]
+      }
+
+      path = outbound_dir.join("#{timestamp}_#{id}.json")
+      File.write(path, JSON.pretty_generate(email_data))
+
+      logger.info("[ResendRobot] Stored outbound #{id} → #{Array(params[:to]).join(", ")} | #{params[:subject]}")
+
+      if should_open_in_browser?
+        open_in_browser(id)
+      end
+
+      { id: id }
+    end
+
+    # Store an inbound email for later retrieval by the shimmed Receiving.get.
+    def store_inbound(email_id, data)
+      ensure_dir(inbound_dir)
+      path = inbound_dir.join("#{email_id}.json")
+      File.write(path, JSON.pretty_generate(data))
+      logger.info("[ResendRobot] Stored inbound #{email_id}")
+    end
+
+    # Fetch a stored inbound email. Called by the shim replacing Receiving.get.
+    def fetch_inbound(email_id)
+      return nil unless email_id.to_s.match?(/\Arl_inbound_[0-9a-f]+\z/)
+      path = inbound_dir.join("#{email_id}.json")
+      return nil unless path.exist?
+
+      JSON.parse(File.read(path), symbolize_names: true)
+    end
+
+    # List outbound emails, newest first. Only parses the first `limit` files.
+    def list_outbound(limit: 20)
+      ensure_dir(outbound_dir)
+      files = Dir.glob(outbound_dir.join("*.json")).sort.reverse.first(limit)
+      files.map { |f| JSON.parse(File.read(f), symbolize_names: true) }
+    end
+
+    # Find a single outbound email by its rl_xxx ID.
+    def find_outbound(id)
+      return nil unless id.to_s.match?(/\Arl_[0-9a-f]+\z/)
+      ensure_dir(outbound_dir)
+      pattern = outbound_dir.join("*_#{id}.json")
+      file = Dir.glob(pattern).first
+      return nil unless file
+
+      JSON.parse(File.read(file), symbolize_names: true)
+    end
+
+    # Most recent outbound email.
+    def last_outbound
+      list_outbound(limit: 1).first
+    end
+
+    # Simulate receiving an inbound email through the real webhook pipeline.
+    #
+    # 1. Stores email body in inbound dir
+    # 2. POSTs to localhost webhook endpoint
+    # 3. Controller fetches via shimmed Receiving.get
+    # 4. Production handle_inbound_email runs unchanged
+    def simulate_inbound(from:, to: nil, subject: "Simulated inbound", body: "Test reply body")
+      email_id = "rl_inbound_#{SecureRandom.hex(8)}"
+
+      # Auto-generate reply-domain address if configured and `to` doesn't match.
+      if config.reply_domain
+        to = ensure_reply_domain(to, config.reply_domain)
+      end
+
+      # Store full email content (shimmed Receiving.get will return this)
+      inbound_data = {
+        id: email_id,
+        from: from,
+        to: Array(to),
+        subject: subject,
+        text: body,
+        html: nil,
+        created_at: Time.now.iso8601
+      }
+      store_inbound(email_id, inbound_data)
+
+      # POST to the real webhook endpoint
+      webhook_payload = {
+        type: "email.received",
+        data: {
+          email_id: email_id,
+          from: from,
+          to: Array(to),
+          subject: subject,
+          text: body
+        }
+      }
+
+      port = config.dev_port
+      uri = URI("http://localhost:#{port}#{config.webhook_path}")
+
+      begin
+        response = Net::HTTP.post(uri, webhook_payload.to_json, "Content-Type" => "application/json")
+        logger.info("[ResendRobot] POSTed inbound webhook → #{response.code}")
+      rescue Errno::ECONNREFUSED
+        logger.error("[ResendRobot] Dev server not running on port #{port}. Start with `bin/dev` first.")
+        raise "Dev server not running on port #{port}. Start with `bin/dev` first."
+      end
+
+      email_id
+    end
+
+    # Remove all stored emails.
+    def clear!
+      FileUtils.rm_rf(outbound_dir)
+      FileUtils.rm_rf(inbound_dir)
+      logger.info("[ResendRobot] Cleared all stored emails")
+    end
+
+    private
+
+    def outbound_dir
+      base_path.join(OUTBOUND_DIR)
+    end
+
+    def inbound_dir
+      base_path.join(INBOUND_DIR)
+    end
+
+    def base_path
+      Pathname.new(@base_dir || config.resolved_storage_path)
+    end
+
+    def ensure_dir(dir)
+      FileUtils.mkdir_p(dir)
+    end
+
+    def logger
+      config.resolved_logger
+    end
+
+    def should_open_in_browser?
+      return false if ENV["OPEN_EMAILS"] == "0"
+      return false if defined?(Rails) && Rails.env.test?
+      config.open_in_browser
+    end
+
+    # Ensure the `to` address includes the reply domain.
+    # If not, generate a cold-inbound address on the reply domain.
+    def ensure_reply_domain(to, reply_domain)
+      if to.nil? || (to.respond_to?(:blank?) && to.blank?) || (to.respond_to?(:empty?) && to.empty?)
+        return "cold-#{SecureRandom.hex(4)}@#{reply_domain}"
+      end
+
+      addresses = Array(to)
+      if addresses.any? { |addr| addr.to_s.include?("@#{reply_domain}") }
+        to
+      else
+        # Prepend a reply-domain address so the webhook controller accepts it
+        ["cold-#{SecureRandom.hex(4)}@#{reply_domain}"] + addresses
+      end
+    end
+
+    def open_in_browser(id)
+      port = config.dev_port
+      mount = config.mount_path.chomp("/")
+      url = "http://localhost:#{port}#{mount}/#{id}"
+      system("open", url)
+    rescue => e
+      logger.warn("[ResendRobot] Could not open browser: #{e.message}")
+    end
+  end
+end

data/lib/resend_robot/tasks/resend_robot.rake

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Resend Robot rake tasks — CLI for dev email interaction.
+# Business logic lives in ResendRobot::Storage (tested, DRY).
+# These tasks are thin orchestration only.
+
+namespace :resend_robot do
+  desc "List recent outbound emails"
+  task outbox: :environment do
+    emails = ResendRobot.list_outbound(limit: 20)
+    if emails.empty?
+      puts "No emails. Send one via ActionMailer to see it here."
+    else
+      puts format("%-20s %-10s %-30s %s", "ID", "Time", "To", "Subject")
+      puts "-" * 90
+      emails.each do |email|
+        time = Time.parse(email[:sent_at]).strftime("%H:%M:%S") rescue email[:sent_at]
+        to = Array(email[:to]).first.to_s[0..27]
+        puts format("%-20s %-10s %-30s %s", email[:id], time, to, email[:subject])
+      end
+    end
+  end
+
+  desc "Show a specific outbound email by ID"
+  task :show, [:id] => :environment do |_t, args|
+    email = ResendRobot.find_outbound(args[:id])
+    if email.nil?
+      puts "Email not found: #{args[:id]}"
+    else
+      puts JSON.pretty_generate(email)
+    end
+  end
+
+  desc "Simulate receiving an inbound email"
+  task :receive, [:from, :to, :subject, :body] => :environment do |_t, args|
+    email_id = ResendRobot.simulate_inbound(
+      from: args[:from],
+      to: args[:to].presence,
+      subject: args[:subject] || "Simulated inbound",
+      body: args[:body] || "Test reply body"
+    )
+    puts "Inbound email stored and webhook POSTed: #{email_id}"
+  end
+
+  desc "Reply to the Nth most recent outbound email (0 = most recent)"
+  task :reply, [:index, :body] => :environment do |_t, args|
+    index = (args[:index] || "0").to_i
+    body = args[:body] || "Simulated reply from Resend Robot"
+
+    emails = ResendRobot.list_outbound(limit: index + 1)
+    email = emails[index]
+    if email.nil?
+      puts "No outbound email at index #{index}. Run `bin/rails resend_robot:outbox` to see available emails."
+      next
+    end
+
+    reply_to = Array(email[:reply_to]).first
+    to_address = Array(email[:to]).first
+
+    puts "Replying to: #{email[:subject]}"
+    puts "  From: #{to_address} (original recipient)"
+    puts "  To: #{reply_to} (reply-to address)"
+
+    email_id = ResendRobot.simulate_inbound(
+      from: to_address,
+      to: reply_to,
+      subject: "Re: #{email[:subject]}",
+      body: body
+    )
+    puts "Inbound email stored and webhook POSTed: #{email_id}"
+  end
+
+  desc "Clear all Resend Robot emails"
+  task clear: :environment do
+    ResendRobot.clear!
+    puts "Resend Robot mailbox cleared."
+  end
+end

data/lib/resend_robot/test_helper.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Minitest assertions for verifying emails sent via Resend Robot.
+#
+# Usage:
+#   class UserSignupTest < ActiveSupport::TestCase
+#     include ResendRobot::TestHelper
+#
+#     test "sends welcome email on signup" do
+#       clear_emails
+#       User.create!(email: "alice@example.com")
+#       assert_email_sent_to "alice@example.com", subject: /Welcome/
+#       assert_equal 1, emails_sent.count
+#     end
+#   end
+#
+module ResendRobot
+  module TestHelper
+    # All outbound emails stored since last clear.
+    def emails_sent
+      ResendRobot.list_outbound(limit: 1000)
+    end
+
+    # Most recent outbound email (symbol-keyed hash).
+    def last_email
+      ResendRobot.last_outbound
+    end
+
+    # Clear all stored emails. Call in setup to isolate tests.
+    def clear_emails
+      ResendRobot.clear!
+    end
+
+    # Assert that at least one email was sent to the given address.
+    # Optionally match subject (String or Regexp).
+    def assert_email_sent_to(address, subject: nil, message: nil)
+      matching = emails_sent.select do |email|
+        to_match = Array(email[:to]).any? { |to| to.include?(address) }
+        subject_match = case subject
+                        when nil then true
+                        when Regexp then email[:subject]&.match?(subject)
+                        when String then email[:subject] == subject
+                        else true
+                        end
+        to_match && subject_match
+      end
+
+      msg = message || "Expected an email to #{address}"
+      msg += " with subject matching #{subject.inspect}" if subject
+      msg += ", but found #{emails_sent.count} email(s): #{emails_sent.map { |e| "#{Array(e[:to]).join(',')} | #{e[:subject]}" }.join('; ')}"
+
+      assert matching.any?, msg
+    end
+
+    # Assert that no emails were sent.
+    def assert_no_emails_sent(message: nil)
+      msg = message || "Expected no emails sent, but found #{emails_sent.count}"
+      assert emails_sent.empty?, msg
+    end
+  end
+end

data/lib/resend_robot/version.rb

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

data/lib/resend_robot.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "resend_robot/version"
+require "resend_robot/configuration"
+
+# Resend Robot — dev-mode Resend API shim
+#
+# Like letter_opener, but for the Resend gem. Intercepts Resend API calls
+# in development, stores emails as JSON on disk, and provides a web UI
+# to browse, preview, and simulate replies.
+#
+# Zero config needed — just add to your Gemfile:
+#
+#   gem "resend_robot", group: :development
+#
+module ResendRobot
+  autoload :Storage,       "resend_robot/storage"
+  autoload :Shim,          "resend_robot/shim"
+  autoload :TestHelper,    "resend_robot/test_helper"
+  autoload :HtmlSanitizer, "resend_robot/html_sanitizer"
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+      @storage = nil # reset so new config takes effect
+    end
+
+    def storage
+      @storage ||= Storage.new(configuration)
+    end
+
+    # Allow overriding storage (for tests)
+    attr_writer :storage
+
+    # ── Convenience delegations to Storage ──
+
+    def store_outbound(params)
+      storage.store_outbound(params)
+    end
+
+    def list_outbound(limit: 20)
+      storage.list_outbound(limit: limit)
+    end
+
+    def find_outbound(id)
+      storage.find_outbound(id)
+    end
+
+    def last_outbound
+      storage.last_outbound
+    end
+
+    def store_inbound(email_id, data)
+      storage.store_inbound(email_id, data)
+    end
+
+    def fetch_inbound(email_id)
+      storage.fetch_inbound(email_id)
+    end
+
+    def simulate_inbound(from:, to: nil, subject: "Simulated inbound", body: "Test reply body")
+      storage.simulate_inbound(from: from, to: to, subject: subject, body: body)
+    end
+
+    def clear!
+      storage.clear!
+    end
+  end
+end
+
+require "resend_robot/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: resend_robot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Garry Tan
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: resend
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: Intercepts Resend gem API calls in development, stores emails as JSON,
+  and provides a web UI to browse, preview, and simulate replies. Production code
+  runs unchanged — same pipeline in dev and prod.
+email:
+- garry@garryslist.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- app/controllers/resend_robot/mailbox_controller.rb
+- app/views/resend_robot/mailbox/index.html.erb
+- app/views/resend_robot/mailbox/show.html.erb
+- lib/generators/resend_robot/install_generator.rb
+- lib/generators/resend_robot/templates/initializer.rb
+- lib/generators/resend_robot/templates/skills/resend-robot-read/skill.md
+- lib/generators/resend_robot/templates/skills/resend-robot-send/skill.md
+- lib/resend_robot.rb
+- lib/resend_robot/configuration.rb
+- lib/resend_robot/engine.rb
+- lib/resend_robot/html_sanitizer.rb
+- lib/resend_robot/shim.rb
+- lib/resend_robot/storage.rb
+- lib/resend_robot/tasks/resend_robot.rake
+- lib/resend_robot/test_helper.rb
+- lib/resend_robot/version.rb
+homepage: https://github.com/garrytan/resend_robot
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: Dev-mode Resend API shim — like letter_opener for the Resend gem
+test_files: []