resend_robot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8b7d0f765f0c9920e99d5cd92d614d1a4557adc36907c411ac1e27e919b4ff47
+  data.tar.gz: b1dd5181eb64bb2c13a35b14c15f2589e31a08a0c65fcf562f6ae7f8d8ded38c
+SHA512:
+  metadata.gz: 594c4e376576f217f51b226a16447a22f70cdaaa79ea478728fddd219ec862c4fcf73e990f0ed6fcec9c65ba8bcf112783cf6e3e32530a73daf6aebb7a6dd28e
+  data.tar.gz: ac17dcfc04c8dab6567de3a3bc44c97bf6d0ea2550615b9019dcf9afe9bbcd9bf2c5501c128a569d76e7ca6784dae5e508e598a2961ec2faecf77ff4bdd971a6

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garry Tan
+
+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,179 @@
+# Resend Robot
+
+**letter_opener for the [Resend](https://resend.com) gem.**
+
+Intercepts Resend API calls in development, stores emails as JSON on disk, and provides a web UI to browse, preview, and simulate replies. Production code runs unchanged — same pipeline in dev and prod.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "resend_robot", group: :development
+```
+
+Run `bundle install`, then run the install generator:
+
+```bash
+bin/rails generate resend_robot:install
+```
+
+This creates:
+- `config/initializers/resend_robot.rb` — configuration (reply domain, mount path, etc.)
+- `.claude/skills/resend-robot-read/skill.md` — Claude skill for reading dev emails
+- `.claude/skills/resend-robot-send/skill.md` — Claude skill for simulating inbound emails
+
+The generator is safe to re-run — it will ask before overwriting existing files.
+
+Resend Robot automatically:
+- Installs shims that intercept `Resend::Emails.send`, `Resend::Batch.send`, etc.
+- Sets a dummy API key so `Resend::Mailer` doesn't raise
+- Injects routes at `/dev/email` for the web UI
+- Provides rake tasks for CLI interaction
+
+## Web UI
+
+Visit `http://localhost:3000/dev/email` to browse your dev mailbox:
+
+- **Outbox** — all intercepted emails, newest first, with search/filter
+- **Preview** — inline HTML rendering with sanitization (no iframes)
+- **Reply** — simulate inbound email through your real webhook pipeline
+
+## Configuration
+
+```ruby
+# config/initializers/resend_robot.rb
+ResendRobot.configure do |config|
+  config.reply_domain = "reply.example.com"  # required for inbound simulation
+  config.webhook_path = "/webhooks/resend"   # default
+  config.dev_port = 3000                     # auto-detected from action_mailer
+  config.open_in_browser = true              # auto-open emails in browser
+  config.mount_path = "/dev/email"           # change to mount UI elsewhere
+end
+```
+
+### Bypass the shim
+
+To send real emails via the Resend API in development:
+
+```bash
+RESEND_IN_DEV=1 bin/dev
+```
+
+### Suppress auto-open
+
+```bash
+OPEN_EMAILS=0 bin/dev
+```
+
+## Test Helpers
+
+Resend Robot includes Minitest assertions for verifying emails in your test suite:
+
+```ruby
+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"
+    assert_email_sent_to "alice@example.com", subject: /Welcome/
+    assert_equal 1, emails_sent.count
+    assert_equal "Welcome", last_email[:subject]
+  end
+
+  test "does not send email without signup" do
+    clear_emails
+    assert_no_emails_sent
+  end
+end
+```
+
+### Available assertions
+
+| Method | Description |
+|--------|-------------|
+| `clear_emails` | Clear all stored emails (call in setup) |
+| `emails_sent` | All outbound emails as symbol-keyed hashes |
+| `last_email` | Most recent outbound email |
+| `assert_email_sent_to(addr, subject: nil)` | Assert email was sent to address, optionally matching subject (String or Regexp) |
+| `assert_no_emails_sent` | Assert no emails were sent |
+
+## JSON API
+
+For E2E tests (Playwright, Capybara), the web UI also serves JSON:
+
+```
+GET /dev/email.json          → array of all emails
+GET /dev/email/:id.json      → single email object
+```
+
+## Claude Skills
+
+The install generator adds two [Claude Code](https://claude.ai/claude-code) skills:
+
+| Skill | Description |
+|-------|-------------|
+| `/resend-robot-read` | List, search, and inspect dev emails from the CLI |
+| `/resend-robot-send` | Simulate inbound emails through your webhook pipeline |
+
+These let Claude interact with your dev mailbox conversationally:
+
+- "Show me the last email sent" → runs `/resend-robot-read`
+- "Simulate a reply to the welcome email" → runs `/resend-robot-send`
+
+Skills are plain markdown files in `.claude/skills/` — customize them for your app (e.g., add app-specific models or webhook details).
+
+## Rake Tasks
+
+```bash
+bin/rails resend_robot:outbox              # List recent emails
+bin/rails resend_robot:show[rl_xxx]        # Show specific email
+bin/rails resend_robot:receive[from,to,subject,body]  # Simulate inbound
+bin/rails resend_robot:reply[index,body]   # Reply to Nth most recent
+bin/rails resend_robot:clear               # Clear all emails
+```
+
+## How It Works
+
+Resend Robot monkey-patches 5 Resend gem methods in development:
+
+| Method | Shimmed behavior |
+|--------|-----------------|
+| `Resend::Emails.send` | Stores email as JSON on disk |
+| `Resend::Batch.send` | Stores each email individually |
+| `Resend::Emails::Receiving.get` | Returns stored inbound email |
+| `Resend::Emails::Receiving::Attachments.get` | Returns stub attachment |
+| `Resend::Webhooks.verify` | Returns `true` (bypasses signature validation) |
+
+Your production code (mailers, webhook controllers, inbound email handlers) runs unchanged. The shim operates at the Resend gem boundary — everything downstream is real.
+
+## vs letter_opener
+
+| | letter_opener | Resend Robot |
+|-|---------------|--------------|
+| Works with | SMTP delivery | Resend API client |
+| Storage | Rendered HTML files | JSON (preserves all metadata) |
+| Inbound simulation | No | Yes — POSTs to your real webhook endpoint |
+| Test helpers | No | Yes (`assert_email_sent_to`, etc.) |
+| JSON API | No | Yes (for E2E tests) |
+| Web UI | Basic | Search, filter, reply simulation |
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 7.0
+- [resend](https://github.com/resendlabs/resend-ruby) gem >= 1.0
+
+## Documentation
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — System design, component overview, data flow diagrams
+- [CONTRIBUTING.md](CONTRIBUTING.md) — Dev setup, running tests, project structure
+- [CHANGELOG.md](CHANGELOG.md) — Release history
+- [TODOS.md](TODOS.md) — Planned future work
+
+## License
+
+MIT

data/app/controllers/resend_robot/mailbox_controller.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Dev-only email UI — no auth required.
+# Browse outbound emails, preview HTML, simulate replies through the real
+# webhook pipeline. Inherits from ActionController::Base to avoid
+# host-app before_actions (auth, etc.).
+#
+# rubocop:disable Rails/ApplicationController
+module ResendRobot
+  class MailboxController < ActionController::Base
+    layout false
+
+    before_action :require_local!
+    before_action :set_email, only: %i[show reply]
+
+    # GET /dev/email
+    def index
+      @emails = ResendRobot.list_outbound(limit: 50)
+      respond_to do |format|
+        format.html
+        format.json { render json: @emails }
+      end
+    end
+
+    # GET /dev/email/:id
+    def show
+      head :not_found and return unless @email
+
+      @email_html = ResendRobot::HtmlSanitizer.sanitize(@email[:html]) if @email[:html].present?
+
+      respond_to do |format|
+        format.html
+        format.json { render json: @email }
+      end
+    end
+
+    # POST /dev/email/:id/reply
+    def reply
+      head :not_found and return unless @email
+
+      body = params[:body].presence || 'Simulated reply from Resend Robot'
+      ResendRobot.simulate_inbound(
+        from: Array(@email[:to]).first,
+        to: Array(@email[:reply_to]).first,
+        subject: "Re: #{@email[:subject]}",
+        body: body
+      )
+
+      redirect_to main_app.dev_email_preview_path(@email[:id]),
+                  notice: 'Reply simulated — check InboundEmailHandler logs'
+    rescue StandardError => e
+      redirect_to main_app.dev_email_preview_path(@email[:id]), alert: "Reply failed: #{e.message}"
+    end
+
+    # DELETE /dev/email/clear
+    def clear
+      ResendRobot.clear!
+      redirect_to main_app.dev_email_index_path, notice: 'Resend Robot mailbox cleared'
+    end
+
+    private
+
+    def require_local!
+      head :forbidden unless Rails.env.local?
+    end
+
+    def set_email
+      @email = ResendRobot.find_outbound(params[:id])
+    end
+
+  end
+end
+# rubocop:enable Rails/ApplicationController

data/app/views/resend_robot/mailbox/index.html.erb

@@ -0,0 +1,269 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Resend Robot — Dev Mailbox</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family=Source+Serif+4:opsz,wght@8..60,400;8..60,600&family=DM+Sans:wght@400;500;600&display=swap');
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    body {
+      font-family: 'DM Sans', -apple-system, BlinkMacSystemFont, sans-serif;
+      background: #f8f6f3;
+      color: #334155;
+      min-height: 100vh;
+    }
+
+    a { color: #334155; text-decoration: none; }
+    a:hover { text-decoration: underline; }
+
+    /* ── Top identity bar ── */
+    .identity-bar {
+      background: #1e293b;
+      padding: 10px 24px;
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      border-bottom: 2px solid #be123c;
+    }
+    .identity-bar .logo {
+      font-family: 'Source Serif 4', Georgia, serif;
+      font-weight: 600;
+      font-size: 15px;
+      color: #fbbf24;
+      letter-spacing: -0.01em;
+    }
+    .identity-bar .logo:hover { text-decoration: none; color: #fde68a; }
+    .identity-bar .env-badge {
+      font-size: 10px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.08em;
+      color: #1e293b;
+      background: #fbbf24;
+      padding: 2px 7px;
+      border-radius: 3px;
+    }
+    .identity-bar .count {
+      margin-left: auto;
+      font-size: 12px;
+      color: #94a3b8;
+    }
+
+    /* ── Flash messages ── */
+    .flash {
+      padding: 10px 24px;
+      font-size: 13px;
+      font-weight: 500;
+    }
+    .flash-notice { background: #ecfdf5; color: #065f46; border-bottom: 1px solid #a7f3d0; }
+
+    /* ── Content ── */
+    .content {
+      max-width: 860px;
+      margin: 0 auto;
+      padding: 20px 24px 40px;
+    }
+    .toolbar {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      margin-bottom: 16px;
+    }
+    .toolbar h1 {
+      font-family: 'Source Serif 4', Georgia, serif;
+      font-size: 20px;
+      font-weight: 600;
+      color: #1e293b;
+    }
+    .btn-clear {
+      background: #fff;
+      color: #64748b;
+      border: 1px solid #d1d5db;
+      padding: 6px 14px;
+      border-radius: 5px;
+      font-size: 12px;
+      font-weight: 500;
+      cursor: pointer;
+      font-family: inherit;
+    }
+    .btn-clear:hover { background: #f1f5f9; color: #334155; }
+
+    /* ── Search ── */
+    .search-bar {
+      margin-bottom: 12px;
+    }
+    .search-bar input {
+      width: 100%;
+      padding: 8px 12px;
+      border: 1px solid #d1d5db;
+      border-radius: 5px;
+      font-size: 13px;
+      font-family: inherit;
+      background: #fff;
+      color: #334155;
+    }
+    .search-bar input:focus {
+      outline: none;
+      border-color: #be123c;
+      box-shadow: 0 0 0 2px rgba(190,18,60,0.1);
+    }
+    .search-bar input::placeholder { color: #94a3b8; }
+
+    /* ── Email list ── */
+    .email-list {
+      background: #fff;
+      border: 1px solid #e2e0db;
+      border-radius: 6px;
+      overflow: hidden;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.06);
+    }
+    .email-row {
+      display: grid;
+      grid-template-columns: 1fr auto;
+      gap: 8px;
+      padding: 12px 16px;
+      border-bottom: 1px solid #f1f0ed;
+      transition: background 0.1s;
+      cursor: pointer;
+    }
+    .email-row:last-child { border-bottom: none; }
+    .email-row:hover { background: #fefdfb; }
+    .email-row .subject {
+      font-weight: 500;
+      font-size: 14px;
+      color: #1e293b;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+    .email-row .to-line {
+      font-size: 12px;
+      color: #64748b;
+      margin-top: 2px;
+    }
+    .email-row .to-line .addr {
+      font-family: ui-monospace, 'SF Mono', Monaco, monospace;
+      font-size: 11px;
+      background: #f1f5f9;
+      padding: 0 5px;
+      border-radius: 3px;
+    }
+    .email-row .reply-to-hint {
+      font-size: 11px;
+      color: #94a3b8;
+      margin-top: 2px;
+    }
+    .email-row .time {
+      font-size: 12px;
+      color: #94a3b8;
+      white-space: nowrap;
+      font-family: ui-monospace, 'SF Mono', Monaco, monospace;
+      align-self: start;
+      padding-top: 2px;
+    }
+
+    /* ── Empty state ── */
+    .empty-state {
+      text-align: center;
+      padding: 48px 24px;
+    }
+    .empty-state p {
+      color: #94a3b8;
+      font-size: 14px;
+    }
+    .empty-state .hint {
+      font-size: 12px;
+      margin-top: 8px;
+    }
+
+    .hidden { display: none !important; }
+
+    @media (max-width: 640px) {
+      .content { padding: 12px; }
+      .email-row { grid-template-columns: 1fr; }
+      .email-row .time { font-size: 11px; }
+    }
+  </style>
+</head>
+<body>
+  <div class="identity-bar">
+    <span class="logo">Resend Robot</span>
+    <span class="env-badge">Dev</span>
+    <span class="count"><%= @emails.size %> email<%= @emails.size == 1 ? '' : 's' %></span>
+  </div>
+
+  <% if flash[:notice] %>
+    <div class="flash flash-notice"><%= flash[:notice] %></div>
+  <% end %>
+
+  <div class="content">
+    <div class="toolbar">
+      <h1>Outbox</h1>
+      <% if @emails.any? %>
+        <form action="<%= main_app.dev_email_clear_path %>" method="post" onsubmit="return confirm('Clear all stored emails?')">
+          <input type="hidden" name="_method" value="delete">
+          <input type="hidden" name="authenticity_token" value="<%= form_authenticity_token %>">
+          <button type="submit" class="btn-clear">Clear All</button>
+        </form>
+      <% end %>
+    </div>
+
+    <% if @emails.any? %>
+      <div class="search-bar">
+        <input type="text" id="email-search" placeholder="Filter by subject, to, or from..." autocomplete="off">
+      </div>
+    <% end %>
+
+    <% if @emails.empty? %>
+      <div class="email-list">
+        <div class="empty-state">
+          <p>No emails yet</p>
+          <p class="hint">Emails sent via ActionMailer are intercepted by Resend Robot and stored locally.</p>
+        </div>
+      </div>
+    <% else %>
+      <div class="email-list" id="email-list">
+        <% @emails.each do |email| %>
+          <a href="<%= main_app.dev_email_preview_path(email[:id]) %>" class="email-row"
+             data-subject="<%= email[:subject] %>"
+             data-to="<%= Array(email[:to]).join(' ') %>"
+             data-from="<%= email[:from] %>">
+            <div>
+              <div class="subject"><%= email[:subject] %></div>
+              <div class="to-line">
+                To: <% Array(email[:to]).each do |addr| %><span class="addr"><%= addr %></span> <% end %>
+              </div>
+              <% if Array(email[:reply_to]).any? %>
+                <div class="reply-to-hint">Reply-To: <%= Array(email[:reply_to]).first %></div>
+              <% end %>
+            </div>
+            <div class="time"><%= Time.parse(email[:sent_at]).strftime("%H:%M:%S") rescue email[:sent_at] %></div>
+          </a>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+
+  <script>
+    document.addEventListener('DOMContentLoaded', function() {
+      var search = document.getElementById('email-search');
+      if (!search) return;
+
+      search.addEventListener('input', function() {
+        var query = this.value.toLowerCase();
+        var rows = document.querySelectorAll('#email-list .email-row');
+        rows.forEach(function(row) {
+          var subject = (row.getAttribute('data-subject') || '').toLowerCase();
+          var to = (row.getAttribute('data-to') || '').toLowerCase();
+          var from = (row.getAttribute('data-from') || '').toLowerCase();
+          var match = !query || subject.indexOf(query) !== -1 || to.indexOf(query) !== -1 || from.indexOf(query) !== -1;
+          row.classList.toggle('hidden', !match);
+        });
+      });
+    });
+  </script>
+</body>
+</html>