goodmail 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46415351f6fd50d3944eb427590536c352575a1c49b417920a09664936a5743d
-  data.tar.gz: 23853af7b4d45b9f099cb20538e5a535f2d373e78320337f8400238ca1d99786
+  metadata.gz: 97d19566a8e8eacb10fed28cddfbe7c9f254ae6f4df4b0c2a8ad5259d646631d
+  data.tar.gz: a15578a0b463e3372ffeff6f9d0a2b0aaa3754c0cf604cc574a97fb0506545fe
 SHA512:
-  metadata.gz: 884e71765428aa8cd6d4529c8c451adde02c4b8d8e8053b4bc5ec23aed2612fcf36160afa1b0499795e87f0c6c5952d6dee1ea1510dff0e0a0cdf95531965b2a
-  data.tar.gz: edc98703ff32581d788ff151ded6961f5589446b23a2fe7aba25dfe67bf579ee2d56d1b35b58aa2901ec06f89392eb880b44332a1b8bca594b0a8ef5a9997d3e
+  metadata.gz: 8ec18e8bc6a78545259c5a359b1811fa7df18cccdca0df36761b94db25304ea9f894ae85cbddbeb54c674526ad7eb5c5a80e24767f7bd97d23baa692ab02aa5f
+  data.tar.gz: d384ec22ed4107cb20c73deff523e15b3d5dcaf7c3d5a464030024336fde15e6346f5f02f90673e23d6790e085db70782b2a2e0df783dbd7db8ad23908b8e3ff

data/README.md

@@ -5,6 +5,10 @@ Send beautiful, simple transactional emails with zero HTML hell.
 
 Goodmail turns your ugly, default, text-only emails into SaaS-ready emails. It's an opinionated, minimal, expressive Ruby DSL for sending beautiful, production-grade transactional emails in Rails apps — no templates, no partials, no HTML hell. The template works well and looks nice across email clients.
 
+![Goodmail Example Email](mailgood.webp)
+
+You can easily add buttons, images, links, price lines, and text to your emails, and it'll look good everywhere, no styling needed.
+
 Here's the catch: there's only one template. You can't change it. You're guaranteed you'll send good emails, but the cost is you don't have much flexibility. If you're okay with this, welcome to `goodmail`! You'll be shipping decent emails that look great everywhere in no time.
 
 (And you can still use Action Mailer for all other template-intensive emails – Goodmail doesn't replace Action Mailer, just builds on top of it!)
@@ -45,7 +49,6 @@ Goodmail.configure do |config|
   config.brand_color = "#E62F17"
 
   # Optional: URL to your company logo. If set, it will appear in the header.
-  # Recommended size: max-height 30px.
   # Default: nil
   config.logo_url = "https://cdn.myapp.com/images/email_logo.png"
 
@@ -101,7 +104,7 @@ recipient = User.find(params[:user_id])
 
 mail = Goodmail.compose(
   to: recipient.email,
-  from: ""#{Goodmail.config.company_name} Support" <support@myapp.com>",
+  from: "'#{Goodmail.config.company_name} Support' <support@myapp.com>",
   subject: "Welcome to MyApp!",
   preheader: "Your adventure begins now!" # Optional override
 ) do
@@ -169,6 +172,68 @@ Inside the `Goodmail.compose` block, you have access to these methods:
 *   `sign(name = Goodmail.config.company_name)`: Adds a standard closing signature line.
 *   `html(raw_html_string)`: **Use with extreme caution.** Allows embedding raw, *un-sanitized* HTML.
 
+### Advanced: Rendering Email Parts with `Goodmail.render`
+
+For more advanced use cases, such as integrating Goodmail's content generation into existing mailer workflows (like Devise mailers) or when you need direct access to the generated HTML and plain text parts before sending, Goodmail provides the `Goodmail.render` method.
+
+This method processes your DSL block, applies the layout, runs Premailer for CSS inlining, and performs plain text cleanup, similar to `Goodmail.compose`. However, instead of returning a `Mail::Message` object ready for delivery, it returns a `Goodmail::EmailParts` struct.
+
+The `Goodmail::EmailParts` struct (defined in `goodmail/email.rb`) has two attributes:
+*   `html`: The final, inlined HTML content for your email.
+*   `text`: The cleaned-up plain text version of your email.
+
+**How to use it:**
+
+You can then use these parts within any Action Mailer setup:
+
+```ruby
+# In your custom mailer (e.g., a Devise mailer override)
+
+# Define your headers (to, from, subject, etc.)
+# The :subject is crucial for Goodmail.render.
+# You can also pass :unsubscribe_url and :preheader to Goodmail.render
+# to override global configurations for that specific email.
+# Note: these Goodmail-specific keys will be used by Goodmail.render
+# and should not be passed directly to ActionMailer's mail() method
+# if they are not standard mail headers.
+mail_rendering_headers = {
+  to: recipient.email,
+  from: "notifications@myapp.com",
+  subject: "Important Update for #{recipient.name}",
+  unsubscribe_url: custom_unsubscribe_url_for_user(recipient), # Optional
+  preheader: "A quick update you should see." # Optional
+}
+
+# Render the email parts using Goodmail's DSL
+# Goodmail.render will use :subject, :unsubscribe_url, :preheader internally.
+parts = Goodmail.render(mail_rendering_headers) do
+  h1 "Hello, #{recipient.name}!"
+  text "This is an important update regarding your account."
+  button "View Details", view_details_url(recipient)
+  sign "The MyApp Team"
+end
+
+# Prepare headers for ActionMailer's mail() method,
+# ensuring only standard mail headers are passed.
+action_mailer_headers = mail_rendering_headers.slice(:to, :from, :subject, :cc, :bcc, :reply_to)
+
+# Now use these parts in ActionMailer's mail method
+# You might also want to add the List-Unsubscribe header manually here if needed.
+final_mail_object = mail(action_mailer_headers) do |format|
+  format.html { render html: parts.html.html_safe }
+  format.text { render plain: parts.text }
+end
+
+# The `final_mail_object` returned by ActionMailer can then be delivered:
+# final_mail_object.deliver_now or final_mail_object.deliver_later
+```
+
+**Key Differences from `Goodmail.compose`:**
+
+*   **Return Value**: `Goodmail.render` returns an instance of `Goodmail::EmailParts` (e.g., `EmailParts.new(html: "...", text: "...")`). `Goodmail.compose` returns a `Mail::Message` object.
+*   **Purpose**: `Goodmail.render` is primarily for generating and retrieving processed email content parts. `Goodmail.compose` is for generating a complete, deliverable `Mail::Message` object.
+*   **List-Unsubscribe Header**: `Goodmail.render` itself does *not* add the `List-Unsubscribe` header to any mail object (as it doesn't create one). If you use `Goodmail.render`, you are responsible for adding this header to your `Mail::Message` object if an `unsubscribe_url` was effectively used during rendering (either passed to `Goodmail.render` or taken from global config) and you require this header. The internal `Goodmail::Mailer` (used by `Goodmail.compose`) handles adding this header automatically to the `Mail::Message` object it builds.
+
 ### Adding Unsubscribe Functionality
 
 Goodmail helps you add the `List-Unsubscribe` header and an optional visible link, but **you must provide the actual URL** where users can unsubscribe.
@@ -213,4 +278,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/rameer
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/goodmail/builder.rb

@@ -6,6 +6,9 @@ module Goodmail
   # Builds the HTML content string based on DSL method calls.
   class Builder
     include ERB::Util # For the h() helper
+    # The h helper, included from ERB::Util, stands for html_escape.
+    # It converts special characters (&, <, >, ", ') into their HTML entity equivalents (&amp;, &lt;, &gt;, &quot;, &#39;). This prevents Cross-Site Scripting (XSS) by ensuring dynamic content is displayed as literal text rather than being interpreted as HTML.
+
 
     # Initialize a basic sanitizer allowing only <a> tags with href
     HTML_SANITIZER = Rails::Html::SafeListSanitizer.new
@@ -83,7 +86,7 @@ module Goodmail
     # Adds a simple price row as a styled paragraph.
     # NOTE: This does not create a table structure.
     def price_row(name, price)
-      parts << %(<p style="font-weight:bold; text-align:center; border-top:1px solid #eaeaea; padding:20px 0; margin: 0;">#{h name} &ndash; #{h price}</p>)
+      parts << %(<p style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; font-size: 14px; font-weight:bold; text-align:center; border-top:1px solid #eaeaea; padding:14px 0; margin: 0;">#{h name} &nbsp; &ndash; &nbsp; #{h price}</p>)
     end
 
     # Adds a simple code box with background styling.

data/lib/goodmail/email.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+require "premailer"
+require "cgi" # For unescaping HTML in plaintext generation (though Premailer might handle most)
+
+module Goodmail
+  # Simple struct to hold the rendered HTML and text parts of an email.
+  EmailParts = Struct.new(:html, :text, keyword_init: true)
+
+  # Renders the email content using the Goodmail DSL and returns HTML and text parts.
+  # This method does not send the email but prepares its content for sending.
+  #
+  # @param headers [Hash] Mail headers. Expected to contain :subject.
+  #                       Can also contain :unsubscribe_url and :preheader to override defaults.
+  # @param dsl_block [Proc] Block containing Goodmail DSL calls (text, button, etc.)
+  # @return [Goodmail::EmailParts] An object containing the :html and :text email parts.
+  def self.render(headers = {}, &dsl_block)
+    # 1. Initialize the Builder and execute the DSL block
+    builder = Goodmail::Builder.new
+    builder.instance_eval(&dsl_block) if block_given?
+    core_html_content = builder.html_output
+
+    # 2. Determine unsubscribe_url and preheader
+    #    These are removed from headers as they are Goodmail-specific, not standard mail headers.
+    current_headers = headers.dup # Avoid modifying the original headers hash directly
+    unsubscribe_url = current_headers.delete(:unsubscribe_url) || Goodmail.config.unsubscribe_url
+    preheader = current_headers.delete(:preheader) || Goodmail.config.default_preheader || current_headers[:subject]
+
+    # 3. Render the raw HTML body using the Layout
+    #    The subject is passed for the <title> tag and potentially other uses in layout.
+    #    Unsubscribe URL and preheader are passed for inclusion in the layout.
+    raw_html_body = Goodmail::Layout.render(
+      core_html_content,
+      current_headers[:subject], # Use subject from (potentially modified) current_headers
+      unsubscribe_url: unsubscribe_url,
+      preheader: preheader
+    )
+
+    # 4. Use Premailer to inline CSS and generate plaintext
+    premailer = Premailer.new(
+      raw_html_body,
+      with_html_string: true,
+      adapter: :nokogiri,
+      preserve_styles: false, # Force inlining and remove <style> block
+      remove_ids: true,       # Remove IDs
+      remove_comments: false  # Keep MSO conditional comments
+    )
+
+    final_inlined_html = premailer.to_inline_css
+    generated_plain_text = premailer.to_plain_text
+
+    # 5. Perform refined plaintext cleanup (ported from Goodmail::Mailer)
+    # 5.1. Remove logo alt text line (if logo exists and has associated URL)
+    if Goodmail.config.logo_url.present? && Goodmail.config.company_url.present? && Goodmail.config.company_name.present?
+      company_name_escaped = Regexp.escape(Goodmail.config.company_name)
+      company_url_escaped = Regexp.escape(Goodmail.config.company_url)
+      # Regex to match the typical alt text pattern for a linked logo image
+      logo_alt_pattern = /^\s*#{company_name_escaped}\s+Logo\s*\(.*?#{company_url_escaped}.*?\).*\n?/i
+      generated_plain_text.gsub!(logo_alt_pattern, "")
+    end
+
+    # 5.2. Remove any remaining standalone URL lines (often from logo links or similar artifacts)
+    # This targets lines that consist *only* of a URL.
+    generated_plain_text.gsub!(/^\s*https?:\/\/\S+\s*$\n?/i, "")
+
+    # 5.3. Compact excess blank lines (more than two consecutive newlines)
+    generated_plain_text.gsub!(/\n{3,}/, "\n\n")
+
+    # 6. Return the structured parts
+    EmailParts.new(html: final_inlined_html, text: generated_plain_text.strip)
+  end
+end

data/lib/goodmail/layout.erb

@@ -179,10 +179,10 @@
               <td style="font-family: 'Helvetica Neue',Helvetica,Arial,sans-serif; box-sizing: border-box; font-size: 14px; vertical-align: top; margin: 0; padding: 0;" valign="top">
                 <% if config.company_url.present? %>
                   <a href="<%= config.company_url %>" style="text-decoration:none; border:0;">
-                    <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="30" style="max-height: 30px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
+                    <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="20" style="max-height: 20px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
                   </a>
                 <% else %>
-                  <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="30" style="max-height: 30px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
+                  <img src="<%= config.logo_url %>" alt="<%= config.company_name %> Logo" height="20" style="max-height: 20px; width: auto; border:0; outline:none; text-decoration:none; display:block;" />
                 <% end %>
               </td>
             </tr>

data/lib/goodmail/version.rb

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

data/lib/goodmail.rb

@@ -10,6 +10,7 @@ require_relative "goodmail/configuration"
 require_relative "goodmail/error" # Load Error class explicitly if needed elsewhere
 require_relative "goodmail/builder"
 require_relative "goodmail/layout"
+require_relative "goodmail/email"
 require_relative "goodmail/mailer"     # Require the internal Mailer
 require_relative "goodmail/dispatcher"
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: goodmail
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2025-05-02 00:00:00.000000000 Z
+date: 2025-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -96,11 +96,13 @@ files:
 - lib/goodmail/builder.rb
 - lib/goodmail/configuration.rb
 - lib/goodmail/dispatcher.rb
+- lib/goodmail/email.rb
 - lib/goodmail/error.rb
 - lib/goodmail/layout.erb
 - lib/goodmail/layout.rb
 - lib/goodmail/mailer.rb
 - lib/goodmail/version.rb
+- mailgood.webp
 - sig/goodmail.rbs
 homepage: https://github.com/rameerez/goodmail
 licenses: