letter_thief 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f34879896479445bff76a77165e6f7db08a18880e14df630b76c747f76fc64af
+  data.tar.gz: 6db1a3fde6c19127cb57a939b48e98cbf4183eab230ede479909279edd687923
+SHA512:
+  metadata.gz: 5c772c8efb3b683164e883057ed94bea7497643f1aeb32e39f76a8430e25bea178c69a4d79a8178d93c277cca7e7be055b01892ef726649af33952ed79ea1edb
+  data.tar.gz: 05dfe63a3bfbe3ff7bad33e0ec8e5ca3e46728315cd8ceebabde3d59609b37c69876a991e390f4f9109ec5e3406b178f654aab16dff90f2d6b77b4eb41e9cf25

data/README.md

@@ -0,0 +1,122 @@
+# LetterThief
+
+<img alt="logo.webp" src="logo.png" width="150px"/>
+
+**A Rails engine to log email deliveries, visualize them in the Browser and, if you want, intercept them.**
+
+This gem allows you to log on the database the emails sent by your application.
+
+It provides an interface to visualize the emails directly in the Browser, and search them.
+
+You can of course navigate and search your emails using ActiveRecord `LetterThief::EmailMessage` model and integrate it
+other parts of your app.
+
+> List of interecepted email
+![screenshot1.png](screenshot1.png)
+
+> Email preview
+![screenshot2.png](screenshot2.png)
+
+You can also use `Letter Thief` as a delivery method in your application as well.
+
+Set `config.action_mailer.delivery_method = :letter_thief` to stop sending emails and have them only logged in your
+database. That's particularly useful in development environments or staging/pre-production environments as well.
+
+If you used `letter_opener` in the past you know how nice it is to have
+the sent emails opened automatically in your Browser when working locally.
+LetterThief supports this as well with the very same mechanism, but `launchy` is not a direct dependency.
+If you add Launchy on your Gemfile, emails will be opened right away once sent.
+
+Since emails are persisted on the Database it means you can use this also on Heroku, deplo.io, or other PaaS where you
+don't have a disk. No need for an external service like Mailtrap (amazing service!) anymore.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "letter_thief"
+```
+
+And then execute:
+
+```bash
+bundle install
+bin/rails generate letter_thief:install
+bin/rails db:migrate
+```
+
+This will create the necessary tables.
+
+If you want to stop sending emails, you can use it also as delivery method:
+
+```ruby
+config.action_mailer.delivery_method = :letter_thief
+config.action_mailer.raise_delivery_errors = true
+```
+
+If you want emails to be opened immediately, add `launchy` to your Gemfile.
+
+```ruby
+group :development do
+  gem "launchy"
+end
+```
+
+and LetterThief will open emails directly in your Browser like Letter Opener.
+
+### Separate database
+
+If you'd like to store your emails on a separate database, you can configure it via:
+
+`config.letter_thief.connects_to = {database: {writing: :letter_thief}}` and of course you'll need a separate database
+configuration. Here is an example:
+
+```yml
+development:
+  primary:
+    <<: *default
+    database: my_app_development
+  letter_thief:
+    <<: *default
+    database: my_app_letter_thief_development
+    migrations_paths: db/letter_thief_migrate
+```
+
+## Varia
+
+> [!NOTE]
+> Persisting the emails on the database might have privacy related concerns. You might want to encrypt stuff.
+
+> [!NOTE]
+> You might want to schedule a cleanup job to remove old records from time to time.
+
+> [!NOTE]
+> For this gem I was heavily inspired by letter_opener, which I used for over ten years. ❤️
+
+> [!NOTE]
+> I planned to basically just replicate letter_opener but persist emails in the database, so I could use it on Heroku or
+> deplo.io, that's why is called LetterThief. It was supposed to just intercept and block emails from being sent. It
+> ended up being this and also a logging system.
+
+## Development
+
+You can run the tests with `bin/test`. By default they run on sqlite. To run them on postgres or mysql, specify the
+TARGET_DB.
+
+```bash
+bin/test #sqlite
+TARGET_DB=postgres bin/test #postgres
+TARGET_DB=mysql bin/test #mysql
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/coorasse/letter_thief.
+
+Try to be a decent human being while interacting with other people.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/letter_thief/application_controller.rb

@@ -0,0 +1,4 @@
+module LetterThief
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/letter_thief/email_messages_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module LetterThief
+  class EmailMessagesController < ApplicationController
+    layout "letter_thief/application"
+
+    PAGE_SIZE = 20
+
+    def index
+      @search = LetterThief::EmailSearch.new(params).perform
+    end
+
+    def show
+      @email = EmailMessage.find(params[:id])
+    end
+  end
+end

data/app/helpers/letter_thief/application_helper.rb

@@ -0,0 +1,16 @@
+module LetterThief
+  module ApplicationHelper
+    def parsed_body_html(email)
+      rendered = email.body_html
+      email.attachments.each do |attachment|
+        puts attachment.blob.metadata["cid"]
+        rendered.gsub!("cid:#{attachment.blob.metadata["cid"]}", main_app.rails_blob_path(attachment))
+      end
+      # autolinking can be implemented for text bodies
+      # rendered.gsub!(URI::Parser.new.make_regexp(%W[https http])) do |link|
+      #   "<a href=\"#{ link }\">#{ link }</a>"
+      # end
+      rendered
+    end
+  end
+end

data/app/jobs/letter_thief/application_job.rb

@@ -0,0 +1,4 @@
+module LetterThief
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/models/letter_thief/application_record.rb

@@ -0,0 +1,5 @@
+module LetterThief
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/letter_thief/email_message.rb

@@ -0,0 +1,27 @@
+module LetterThief
+  class EmailMessage < ApplicationRecord
+    self.table_name = "letter_thief_email_messages"
+
+    has_many_attached :attachments
+
+    unless ActiveRecord::Base.connection.adapter_name.downcase.include?("postgresql")
+      serialize :to, coder: JSON, type: Array
+      serialize :from, coder: JSON, type: Array
+      serialize :sender, coder: JSON, type: Array
+      serialize :cc, coder: JSON, type: Array
+      serialize :bcc, coder: JSON, type: Array
+    end
+
+    def type
+      /html/.match?(content_type) ? "rich" : "plain"
+    end
+
+    def rich?
+      type == "rich"
+    end
+
+    def multipart?
+      body_text.present? && body_html.present?
+    end
+  end
+end

data/app/models/letter_thief/email_search.rb

@@ -0,0 +1,50 @@
+module LetterThief
+  class EmailSearch
+    PAGE_SIZE = 20
+
+    attr_reader :query, :start_time, :end_time, :page, :total_count, :results, :has_next_page
+
+    def initialize(params)
+      @query = params[:query].to_s.strip
+      @start_time = params[:start_time]
+      @end_time = params[:end_time]
+      @page = params[:page].to_i
+      @page = 1 if @page < 1
+    end
+
+    def perform
+      scope = EmailMessage.order(intercepted_at: :desc)
+
+      if query.present?
+        adapter = ActiveRecord::Base.connection.adapter_name.downcase
+        scope = if adapter.include?("postgresql")
+          scope.where(<<~SQL.squish, q: "%#{query}%")
+            subject ILIKE :q
+            OR array_to_string("from", ',') ILIKE :q
+            OR array_to_string("to", ',') ILIKE :q
+          SQL
+        elsif adapter.include?("mysql")
+          scope.where("`subject` LIKE :q OR `from` LIKE :q OR `to` LIKE :q", q: "%#{query}%")
+        else
+          scope.where('subject LIKE :q OR "from" LIKE :q OR "to" LIKE :q', q: "%#{query}%")
+        end
+      end
+
+      scope = scope.where("intercepted_at >= ?", parse_datetime(start_time)) if start_time.present?
+      scope = scope.where("intercepted_at <= ?", parse_datetime(end_time)) if end_time.present?
+
+      @total_count = scope.count
+      @results = scope.limit(PAGE_SIZE).offset((page - 1) * PAGE_SIZE)
+      @has_next_page = total_count > page * PAGE_SIZE
+      self
+    end
+
+    private
+
+    def parse_datetime(value)
+      DateTime.parse(value) if value.present?
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/views/layouts/letter_thief/application.html.erb

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html style="height:100%">
+<head>
+  <title>Letter thief</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
+</head>
+<body style="height:100%">
+<main class="container" style="height:100%">
+  <%= yield %>
+</main>
+</body>
+</html>

data/app/views/letter_thief/email_messages/index.html.erb

@@ -0,0 +1,92 @@
+<h1>📬 Intercepted Emails</h1>
+
+<form method="get" style="margin-bottom: 1rem;">
+  <fieldset class="grid">
+    <label>
+      Query
+      <input
+        name="query"
+        value="<%= h(@search.query) %>"
+        placeholder="Search by from, to, or subject"/>
+    </label>
+
+    <label>
+      From Time
+      <input
+        type="datetime-local"
+        name="start_time"
+        value="<%= @search.start_time %>"/>
+    </label>
+
+    <label>
+      To Time
+      <input
+        type="datetime-local"
+        name="end_time"
+        value="<%= @search.end_time %>"/>
+    </label>
+
+    <input type="submit" value="Search" style="margin-top: 1.7rem"/>
+
+  </fieldset>
+</form>
+
+
+<% if @search.total_count > 0 %>
+  <p><%= pluralize(@search.total_count, "email") %> found</p>
+
+  <table role="grid">
+    <thead>
+    <tr>
+      <th>From</th>
+      <th>To</th>
+      <th>Subject</th>
+      <th>Time</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% @search.results.each do |email| %>
+      <tr>
+        <td><%= email.from&.join(", ") %></td>
+        <td><%= email.to&.join(", ") %></td>
+        <td>
+          <a href="<%= letter_thief.email_message_path(email) %>">
+            <%= email.subject.presence || "(no subject)" %>
+          </a>
+        </td>
+        <td><%= email.intercepted_at.strftime("%Y-%m-%d %H:%M") %></td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+
+  <nav aria-label="Pagination">
+    <ul style="display: flex; gap: 1rem; list-style: none; padding-left: 0;">
+      <% if @search.page > 1 %>
+        <li>
+          <%= link_to "← Previous", letter_thief.email_messages_path(
+            query: @search.query,
+            start_time: @search.start_time,
+            end_time: @search.end_time,
+            page: @search.page - 1
+          ) %>
+        </li>
+      <% end %>
+
+      <li>Page <%= @search.page %></li>
+
+      <% if @search.has_next_page %>
+        <li>
+          <%= link_to "Next →", letter_thief.email_messages_path(
+            query: @search.query,
+            start_time: @search.start_time,
+            end_time: @search.end_time,
+            page: @search.page + 1
+          ) %>
+        </li>
+      <% end %>
+    </ul>
+  </nav>
+<% else %>
+  <p>No emails found.</p>
+<% end %>

data/app/views/letter_thief/email_messages/show.html.erb

@@ -0,0 +1,124 @@
+<p><a href="<%= letter_thief.email_messages_path %>">&larr; Back to Inbox 📬</a></p>
+
+<section id="message_headers">
+  <dl>
+    <dt>Intercepted at:</dt>
+    <dd><%= @email.intercepted_at.strftime("%b %e, %Y %I:%M %p") %></dd>
+    <% if @email.from.present? %>
+      <dt>From:</dt>
+      <dd><%= @email.from.join(", ") %></dd>
+    <% end %>
+
+    <% if @email.sender.present? %>
+      <dt>Sender:</dt>
+      <dd><%= @email.sender.join(", ") %></dd>
+    <% end %>
+
+    <% if @email.to.present? %>
+      <dt>To:</dt>
+      <dd><%= @email.to.join(", ") %></dd>
+    <% end %>
+
+    <dt>Subject:</dt>
+    <dd><strong><%= h(@email.subject || "(no subject)") %></strong></dd>
+
+    <% if @email.cc.present? %>
+      <dt>CC:</dt>
+      <dd><%= @email.cc.join(", ") %></dd>
+    <% end %>
+
+    <% if @email.bcc.present? %>
+      <dt>BCC:</dt>
+      <dd><%= @email.bcc.join(", ") %></dd>
+    <% end %>
+
+    <% if @email.attachments.any? %>
+      <dt>Attachments:</dt>
+      <dd>
+        <% @email.attachments.each do |file| %>
+          <%= link_to file.filename, main_app.rails_blob_path(file, disposition: "attachment") %>
+        <% end %>
+      </dd>
+    <% end %>
+  </dl>
+</section>
+
+<hr>
+
+<% if @email.multipart? %>
+  <nav>
+    <ul>
+      <li data-version-toggle="html" style="display: none">
+        <a href="#" role="button" class="outline">View HTML version</a></li>
+      <li data-version-toggle="text"><a href="#" role="button" class="outline">View plain text version</a></li>
+    </ul>
+  </nav>
+<% end %>
+
+<section id="email_body" style="height:100%">
+  <% if @email.body_text.present? %>
+    <% if @email.rich? %>
+      <iframe
+        id="text-version"
+        class="email-version"
+        srcdoc="<base target='_top'><%= h(@email.body_text) %>">
+      </iframe>
+    <% else %>
+      <pre class="email-version" id="text-version" style="display: <%= @email.multipart? ? 'none' : 'block' %>"><%= h(@email.body_text) %></pre>
+    <% end %>
+  <% end %>
+
+  <% if @email.body_html.present? %>
+    <iframe
+      id="html-version"
+      class="email-version"
+      srcdoc="<base target='_top'><%= parsed_body_html(@email) %>">
+    </iframe>
+  <% end %>
+</section>
+
+<script>
+    function toggleVersions(version, otherVersion) {
+        document.querySelector(`[data-version-toggle="${version}"]`).addEventListener('click', event => {
+            event.preventDefault()
+            document.querySelector(`[data-version-toggle="${version}"]`).style.display = "none";
+            document.querySelector(`[data-version-toggle="${otherVersion}"]`).style.display = "block";
+
+            document.getElementById(`${version}-version`).style.display = 'block'
+            document.getElementById(`${otherVersion}-version`).style.display = 'none'
+        });
+    }
+
+    toggleVersions("text", "html");
+    toggleVersions("html", "text");
+</script>
+
+<style>
+    #message_headers {
+        dt {
+            color: #7f7f7f;
+            text-align: right;
+            font-weight: bold;
+        }
+
+        dl {
+            display: grid;
+            grid-template-columns: max-content auto;
+            row-gap: 0.5rem;
+            font-size: 0.95rem;
+        }
+    }
+
+    pre {
+        border: 1px solid #ddd;
+        padding: 1rem;
+        white-space: pre-wrap;
+        font-family: monospace;
+    }
+
+    iframe {
+        border: 0;
+        width: 100%;
+        height: 100%;
+    }
+</style>

data/config/routes.rb

@@ -0,0 +1,3 @@
+LetterThief::Engine.routes.draw do
+  resources :email_messages, only: [:index, :show]
+end

data/lib/generators/letter_thief/install_generator.rb

@@ -0,0 +1,24 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module LetterThief
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_migration
+        migration_template "create_email_messages.rb.erb",
+          "db/migrate/create_letter_thief_email_messages.rb",
+          migration_version: migration_version
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/letter_thief/templates/create_email_messages.rb.erb

@@ -0,0 +1,33 @@
+class CreateLetterThiefEmailMessages < ActiveRecord::Migration<%= migration_version %>
+  def change
+    adapter = ActiveRecord::Base.connection.adapter_name.downcase
+
+    create_table :letter_thief_email_messages do |t|
+      if adapter.include?("postgresql")
+        t.string :to, array: true
+        t.string :from, array: true
+        t.string :sender, array: true
+        t.string :cc, array: true
+        t.string :bcc, array: true
+      else
+        t.text :to
+        t.text :from
+        t.text :sender
+        t.text :cc
+        t.text :bcc
+      end
+
+      t.string :subject
+      t.text :body_text
+      t.text :body_html
+      t.text :headers
+      t.text :raw_message
+      t.string :content_type
+      t.datetime :intercepted_at
+
+      t.timestamps
+    end
+
+    add_index :letter_thief_email_messages, :intercepted_at
+  end
+end

data/lib/letter_thief/delivery_method.rb

@@ -0,0 +1,16 @@
+require "digest/sha1"
+
+module LetterThief
+  class DeliveryMethod
+    def initialize(options = {})
+    end
+
+    # this is not really true, we don't know if it's the last email, but for the moment this should do.
+    def deliver!(mail)
+      require "launchy"
+      ::Launchy.open(LetterThief::Engine.routes.url_helpers.email_message_url(LetterThief::EmailMessage.last, Rails.configuration.action_mailer.default_url_options))
+    rescue LoadError
+      puts "WARNING: LetterThief requires the 'launchy' gem to open the email in a web browser. Add it to your Gemfile."
+    end
+  end
+end

data/lib/letter_thief/engine.rb

@@ -0,0 +1,20 @@
+require "letter_thief/interceptor"
+require "letter_thief/delivery_method"
+
+module LetterThief
+  class Engine < ::Rails::Engine
+    isolate_namespace LetterThief
+
+    initializer "letter_thief.add_interceptor" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.register_interceptor(LetterThief::Interceptor)
+      end
+    end
+
+    initializer "letter_thief.add_delivery_method" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method(:letter_thief, LetterThief::DeliveryMethod)
+      end
+    end
+  end
+end

data/lib/letter_thief/interceptor.rb

@@ -0,0 +1,32 @@
+module LetterThief
+  class Interceptor
+    def self.delivering_email(mail)
+      email = EmailMessage.create!(
+        to: mail.to,
+        from: mail.from,
+        sender: mail.sender,
+        cc: mail.cc,
+        bcc: mail.bcc,
+        subject: mail.subject,
+        body_text: mail.text_part&.decoded || mail.body.decoded,
+        body_html: mail.html_part&.decoded,
+        headers: mail.header.to_s,
+        raw_message: mail.to_s,
+        content_type: mail.content_type,
+        intercepted_at: Time.current
+      )
+
+      Array(mail.attachments).each do |attachment|
+        ar_attachment = email.attachments.attach(
+          io: StringIO.new(attachment.body.decoded),
+          filename: attachment.filename,
+          content_type: attachment.mime_type
+        ).last
+        ar_attachment.blob.metadata["cid"] = attachment.cid
+        ar_attachment.blob.save!
+      end
+    rescue => e
+      Rails.logger.error("[LetterThief] Failed to store intercepted email: #{e.message}")
+    end
+  end
+end

data/lib/letter_thief/version.rb

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

data/lib/letter_thief.rb

@@ -0,0 +1,6 @@
+require "letter_thief/version"
+require "letter_thief/engine"
+
+module LetterThief
+  # Your code goes here...
+end

data/lib/tasks/letter_thief_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :letter_thief do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: letter_thief
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alessandro Rodi
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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: LetterThief allows you to record sent emails in your database.
+email:
+- rodi@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- app/controllers/letter_thief/application_controller.rb
+- app/controllers/letter_thief/email_messages_controller.rb
+- app/helpers/letter_thief/application_helper.rb
+- app/jobs/letter_thief/application_job.rb
+- app/models/letter_thief/application_record.rb
+- app/models/letter_thief/email_message.rb
+- app/models/letter_thief/email_search.rb
+- app/views/layouts/letter_thief/application.html.erb
+- app/views/letter_thief/email_messages/index.html.erb
+- app/views/letter_thief/email_messages/show.html.erb
+- config/routes.rb
+- lib/generators/letter_thief/install_generator.rb
+- lib/generators/letter_thief/templates/create_email_messages.rb.erb
+- lib/letter_thief.rb
+- lib/letter_thief/delivery_method.rb
+- lib/letter_thief/engine.rb
+- lib/letter_thief/interceptor.rb
+- lib/letter_thief/version.rb
+- lib/tasks/letter_thief_tasks.rake
+homepage: https://github.com/coorasse/letter_thief
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/coorasse/letter_thief
+  source_code_uri: https://github.com/coorasse/letter_thief
+  changelog_uri: https://github.com/coorasse/letter_thief/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Log emails in Rails and visualize them.
+test_files: []