supermail 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5007ee69916bd3c91239105a78c65ac3fc6729adb206e914881166480cca8d63
-  data.tar.gz: 903ba6a76b34ec3f64d8dc0f4bab2d8782a3ea90c727dbec5647d8e8b99a3376
+  metadata.gz: ab203ffd27a2af74aa3f64e1d0f82fda4263ee4c818072cabd6e9daa5e8afe73
+  data.tar.gz: 2ea834cd01184581f56de63a9e03a708e51c036e37536588bc3143014fe57277
 SHA512:
-  metadata.gz: d696046239e5c7bbb875b291ca99fc2533127f72babac2991ace61520522dc095788506857c1b8cc56c91f74e5c5f24de9db88a3046421ea10e9a677ac6fb4c1
-  data.tar.gz: c2e1303de634498310018e9edbecbb1f0718b545698f56b378d172b4a1fc11389d572ab35019a6bf419faf345b8554b27f95181f4c2ec4e4b0ddca4c81da6c78
+  metadata.gz: 71dd7876ad4759ab40022e6950366f9aad994cfe0e9cbd5f3baeba709de6b40ba4d804b8d864710a7138c9203273caaa61d67955cdaada57a2eb5f0496080a9d
+  data.tar.gz: 4d879602a5ba9fc46ea510428d9ab798f8fb9a0c0c4110b4c002d054737cf0816406cdac30f9edda02bc8640e93b84bc028df931f28516804c23597d2b623f12

data/README.md

@@ -5,16 +5,16 @@ Organize emails with plain 'ol Ruby objects in a Rails application, like this:
 ```ruby
 # ./app/email/user/welcome.rb
 class User::WelcomeEmail < ApplicationEmail
-  def initialize(person:)
-    @person = person
+  def initialize(user:)
+    @user = user
   end
 
-  def to = @person.email
+  def to = @user.email
   def subject = "Welcome to Beautiful Ruby"
   def body
     super do
       <<~_
-      Hi #{@person.name},
+      Hi #{@user.name},
 
       You're going to learn a ton at https://beautifulruby.com.
       _
@@ -25,6 +25,13 @@ end
 
 Contrast that with rails ActionMailer, where you will spend 20 minutes trying to figure out how to send an email. I created this gem because I got tired of digging through Rails docs to understand how to intialize an email and send it. PORO's FTW!
 
+## Support this project
+
+Learn how to build UI's out of Ruby classes and support this project by ordering the [Phlex on Rails video course](https://beautifulruby.com/phlex).
+
+[![](https://immutable.terminalwire.com/hmM9jvv7yF89frBUfjikUfRmdUsTVZ8YvXc7OnnYoERXfLJLzDcj5dFM7qdfMG2bqQLuw633Zt1gl3O7z0zKmH6k8QmifN7z0kJo.png)](https://beautifulruby.com/phlex/forms/introduction)
+
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -76,21 +83,21 @@ class User::WelcomeEmail < ApplicationEmail
   PLAIN
 end
 ```
-
+You can customize the email by overriding the `to`, `from`, `subject`, and `body` methods.s
 
 ```ruby
 # ./app/email/user/welcome.rb
 class User::WelcomeEmail < ApplicationEmail
-  def initialize(person:)
-    @person = person
+  def initialize(user:)
+    @user = user
   end
 
-  def to = @person.email
+  def to = @user.email
   def subject = "Welcome to the website"
   def body
     super do
       <<~_
-      Hi #{@person.name},
+      Hi #{@user.name},
 
       Welcome to the website We're excited to have you on board.
       _
@@ -99,6 +106,8 @@ class User::WelcomeEmail < ApplicationEmail
 end
 ```
 
+### Send emails from the server
+
 Then, to send the email.
 
 ```ruby
@@ -113,6 +122,41 @@ User::Welcome.new(user: User.first).message.tap do
 end.deliver_now
 ```
 
+### Launch the user's email client
+
+Supermail clases can be used to generate `mailto:` links with Rails helpers.
+
+```erb
+<%= link_to Support::OrderEmail.new(
+      user: current_user,
+      order: @order
+    ).mail_to s%>
+```
+
+This opens your users email client with prefilled information. A support email about an order might look like this:
+
+```ruby
+class Support::OrderEmail < ApplicationEmail
+  def initialize(user:, order:)
+    @user = user
+    @order = order
+  end
+
+  def to = "support@example.com"
+  def from = @user.email
+  def subject = "Question about order #{@order.id}"
+  def body = <<~BODY
+    Hi Support,
+
+    I need help with my order #{@order.id}.
+
+    Thanks,
+
+    #{@user.name}
+  BODY
+end
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/generators/supermail/email/email_generator.rb

@@ -3,23 +3,28 @@
 require 'rails/generators/named_base'
 
 module Supermail
-  class EmailGenerator < Rails::Generators::NamedBase
+  class EmailGenerator < ::Rails::Generators::NamedBase
     source_root File.expand_path('templates', __dir__)
 
     desc "Generate a new email class"
 
     def create_email_file
-      template 'email.rb', "app/emails/#{file_path}_email.rb"
+      template 'email.rb', "app/emails/#{file_path}.rb"
     end
 
     private
 
     def file_path
-      name.underscore
+      "#{base_name.underscore}_email"
     end
 
     def class_name
-      name.camelize
+      "#{base_name.camelize}Email"
+    end
+
+    def base_name
+      stripped = name.to_s.sub(/_?email\z/i, '')
+      stripped.empty? ? name : stripped
     end
   end
-end
+end

data/lib/generators/supermail/email/templates/email.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class <%= class_name %>Email < ApplicationEmail
+class <%= class_name %> < ApplicationEmail
   def body = <<~PLAIN
 
   PLAIN

data/lib/generators/supermail/install/install_generator.rb

@@ -3,7 +3,7 @@
 require 'rails/generators/base'
 
 module Supermail
-  class InstallGenerator < Rails::Generators::Base
+  class InstallGenerator < ::Rails::Generators::Base
       source_root File.expand_path('templates', __dir__)
 
       desc "Install Supermail in a Rails application"
@@ -16,4 +16,4 @@ module Supermail
         empty_directory 'app/emails'
       end
   end
-end
+end

data/lib/generators/supermail/install/templates/application_email.rb.tt

@@ -1,4 +1,4 @@
-class ApplicationEmail < Supermail::Base
+class ApplicationEmail < Supermail::Rails::Base
   def from = "website@example.com"
 
   def body

data/lib/supermail/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Supermail
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/supermail.rb

@@ -1,30 +1,77 @@
 # frozen_string_literal: true
 
 require_relative "supermail/version"
-require 'action_mailer'
+require "action_mailer"
+require "erb"
 
 module Supermail
   class Error < StandardError; end
 
-  class Base
-    delegate :deliver, :deliver_now, :deliver_later, to: :message_delivery
+  module Rails
+    # This is a bizzare work around for a commit that broke https://github.com/rails/rails/commit/c594ba4ffdb016c7b2a22055f41dfb2c4409594d
+    # further proving the bewildering maze of indirection in Rails ActionMailer.
+    class Mailer < ActionMailer::Base
+      def mail(...)
+        super(...)
+      end
 
-    def to = nil
-    def from = nil
-    def subject = nil
-    def body = ""
-
-    def message
-      message_delivery.message
+      def self.message_delivery(**)
+        ActionMailer::MessageDelivery.new self, :mail, **
+      end
     end
 
-    def message_delivery
-      ActionMailer::Base.mail(to:, from:, subject:, body:)
+    class Base
+      delegate \
+          :deliver,
+          :deliver_now,
+          :deliver_later,
+          :message,
+        to: :message_delivery
+
+      def to = nil
+      def from = nil
+      def subject = nil
+      def cc = []
+      def bcc = []
+      def body = ""
+
+      # Generate a mailto: URL with appropriate escaping.
+      def mailto = MailTo.href(to:, from:, cc:, bcc:, subject:, body:)
+      alias :mail_to :mailto
+
+      private def message_delivery
+        Rails::Mailer.message_delivery(
+          to:,
+          from:,
+          cc:,
+          bcc:,
+          subject:,
+          body:
+        )
+      end
     end
   end
-end
 
-# Load generators only when Rails is available
-if defined?(::Rails)
-  require 'rails'
+  module MailTo
+    extend self
+
+    def href(to:, **params)
+      q = query(**params)
+      q.empty? ? "mailto:#{to}" : "mailto:#{to}?#{q}"
+    end
+
+    def query(**params)
+      params
+        .compact                          # drop nils
+        .reject { |k, v| v.is_a?(Array) && v.empty? }  # drop empty arrays
+        .map { |k, v| "#{k}=#{mailto_escape(v)}" }
+        .join("&")
+    end
+
+    private
+
+    def mailto_escape(str)
+      ERB::Util.url_encode(str.to_s).tr("+", "%20")
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: supermail
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Brad Gessler
 bindir: exe
 cert_chain: []
-date: 2025-09-26 00:00:00.000000000 Z
+date: 2025-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionmailer