goodmail 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97d19566a8e8eacb10fed28cddfbe7c9f254ae6f4df4b0c2a8ad5259d646631d
-  data.tar.gz: a15578a0b463e3372ffeff6f9d0a2b0aaa3754c0cf604cc574a97fb0506545fe
+  metadata.gz: 49fc7b9412bf9c59d6f4369f8a5ba26f7faaeffd982e98684dd294728254f1e9
+  data.tar.gz: 858a30035cba78799ee8b133d3531e531e952658d9270f35a80ed1fd9cf982ea
 SHA512:
-  metadata.gz: 8ec18e8bc6a78545259c5a359b1811fa7df18cccdca0df36761b94db25304ea9f894ae85cbddbeb54c674526ad7eb5c5a80e24767f7bd97d23baa692ab02aa5f
-  data.tar.gz: d384ec22ed4107cb20c73deff523e15b3d5dcaf7c3d5a464030024336fde15e6346f5f02f90673e23d6790e085db70782b2a2e0df783dbd7db8ad23908b8e3ff
+  metadata.gz: 74d2b6dd4665aa63b5394d715d043193d03e64f0130913442f596db2663d546386bb06ea4fb6940966932877a09751b53972e95bbff619ec0d994fbcd29fc9af
+  data.tar.gz: 8469b9ea99e5de6b53f6c31c4edfb53c4eaee37eb5bf557351a9576456f5907b4fc032f3cb916961c595063f2449584d63ec038c5bc903ab21c2a8ab495fe791

data/.rubocop.yml

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/**/*'
+    - 'examples/**/*'
+    - 'coverage/**/*'
+    - 'pkg/**/*'
+    - 'test/**/*'
+    - 'vendor/**/*'
+    - 'test/dummy/**/*'
+    - 'db/migrate/**/*'  # Generated migrations
+    - 'lib/generators/**/templates/**/*'  # Generator templates
+
+# Layout & Formatting
+Layout/LineLength:
+  Max: 120
+  AllowedPatterns:
+    - '\s*#.*'  # Allow long comments
+    - '^\s*raise\s'  # Allow long raise statements
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_first_argument
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent
+
+# Style
+Style/Documentation:
+  Enabled: false  # Don't require class documentation for now
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+Style/GuardClause:
+  MinBodyLength: 3
+
+# Metrics
+Metrics/ClassLength:
+  Max: 220
+
+Metrics/ModuleLength:
+  Max: 260
+
+Metrics/MethodLength:
+  Max: 40
+  AllowedMethods:
+    - 'configure'  # Configuration blocks can be longer
+
+Metrics/BlockLength:
+  Max: 40
+  AllowedMethods:
+    - 'configure'
+    - 'describe'
+    - 'context'
+    - 'it'
+    - 'test'
+  Exclude:
+    - 'test/**/*'  # Allow long test blocks
+    - 'goodmail.gemspec'
+
+Metrics/AbcSize:
+  Max: 50
+  AllowedMethods:
+    - 'configure'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 6
+
+# Naming
+Naming/PredicatePrefix:
+  ForbiddenPrefixes:
+    - 'is_'
+  AllowedMethods:
+    - 'is_a?'
+
+Naming/MethodParameterName:
+  MinNameLength: 1
+
+Naming/BlockForwarding:
+  Enabled: false
+
+# Performance
+Performance/StringReplacement:
+  Enabled: true
+
+Performance/RedundantMerge:
+  Enabled: true
+
+# Minitest
+Minitest/MultipleAssertions:
+  Enabled: false  # Allow multiple assertions in integration tests
+
+Minitest/AssertTruthy:
+  Enabled: false  # Allow assert instead of assert_equal true
+
+# Custom overrides for this gem
+Style/AccessorGrouping:
+  Enabled: false  # Allow separate attr_reader/attr_writer
+
+Style/MutableConstant:
+  Enabled: false  # We have some intentionally mutable constants
+
+Style/Alias:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/ConditionalAssignment:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/OpenStructUse:
+  Enabled: false
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+
+Style/RedundantRegexpArgument:
+  Enabled: false
+
+Style/RegexpLiteral:
+  Enabled: false
+
+Style/RescueStandardError:
+  Enabled: false
+
+Style/StringLiteralsInInterpolation:
+  Enabled: false
+
+Style/Next:
+  Enabled: false
+
+# Allow class variables for registry pattern
+Style/ClassVars:
+  Enabled: false
+
+# Allow metaprogramming patterns common in Rails engines
+Style/EvalWithLocation:
+  Enabled: false
+
+Lint/MissingSuper:
+  Enabled: false  # Allow classes that don't call super
+
+# Disable some cops that don't work well with our DSL
+Style/MethodCallWithoutArgsParentheses:
+  Enabled: false  # Our DSL looks better without parens
+
+Layout/EmptyLineAfterMagicComment:
+  Enabled: false
+
+Layout/EmptyLinesAfterModuleInclusion:
+  Enabled: false
+
+Layout/HashAlignment:
+  Enabled: false
+
+Layout/CommentIndentation:
+  Enabled: false
+
+Lint/UselessConstantScoping:
+  Enabled: false
+
+# Thread safety
+Style/GlobalVars:
+  AllowedVariables: ['$0']  # Only allow program name
+
+# Database-related
+Style/NumericLiterals:
+  Enabled: false  # Allow raw numbers in database IDs/amounts

data/.simplecov

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SimpleCov configuration file, loaded by test/test_helper.rb when
+# COVERAGE=1 is set. Normal test runs skip coverage instrumentation.
+
+SimpleCov.start do
+  # Use SimpleFormatter for terminal-only output (no HTML generation)
+  formatter SimpleCov::Formatter::SimpleFormatter
+  use_merging false
+
+  # Track coverage for the lib directory (gem source code)
+  add_filter "/test/"
+
+  # `lib/goodmail/version.rb` is loaded by Bundler (via the gemspec
+  # `require_relative "lib/goodmail/version"`) BEFORE SimpleCov starts,
+  # so its lines never get instrumented even though they're executed.
+  # Excluding it keeps the report honest. Goodmail::VERSION's shape is
+  # asserted in `test/goodmail_module_test.rb` instead.
+  add_filter "/lib/goodmail/version.rb"
+
+  # Track Ruby files in lib directory
+  track_files "lib/**/*.rb"
+
+  # Enable branch coverage for more detailed metrics
+  enable_coverage :branch
+
+  # Set minimum coverage threshold to prevent coverage regression.
+  # Goodmail currently sits at 100% line coverage; the branch floor is set
+  # generously to allow non-trivial future additions without immediately
+  # tripping CI.
+  minimum_coverage line: 90, branch: 80
+
+  # Disambiguate parallel test runs
+  command_name "Job #{ENV['TEST_ENV_NUMBER']}" if ENV["TEST_ENV_NUMBER"]
+end
+
+# Print coverage summary to terminal after tests complete
+SimpleCov.at_exit do
+  SimpleCov.result.format!
+  if ENV["COVERAGE_DETAIL"]
+    SimpleCov.result.files.each do |file|
+      missed_lines = file.missed_lines.map(&:line_number)
+      next if missed_lines.empty?
+
+      puts "#{file.filename}:#{missed_lines.join(',')}"
+    end
+  end
+  puts "\n#{'=' * 60}"
+  puts "COVERAGE SUMMARY"
+  puts "=" * 60
+  puts "Line Coverage:   #{SimpleCov.result.covered_percent.round(2)}%"
+  branch_coverage = SimpleCov.result.coverage_statistics[:branch]&.percent&.round(2) || "N/A"
+  puts "Branch Coverage: #{branch_coverage}%"
+  puts "=" * 60
+end

data/CHANGELOG.md

@@ -1,3 +1,79 @@
+## [0.4.0] - 2026-05-08
+
+A polish-and-correctness release. Adds five new DSL helpers, a comprehensive Minitest 6 test suite (100% line coverage), and fixes nine real-world bugs that surfaced after running every email shape through Mailcatcher and inspecting the rendered HTML, plaintext, headers, and attachments end-to-end. The bug fixes are the headline — most of them silently degraded plaintext quality, deliverability, or accessibility before; downstream apps inherit the fixes for free on upgrade.
+
+### Added
+
+#### DSL helpers
+- **`link(text, url)`** — inline styled text link rendered in the configured `brand_color`. Cleaner than hand-writing `<a>` tags inside `text` blocks when the whole paragraph is the link.
+- **`small(text)`** — small grey paragraph for fine print, legal disclaimers, and "you are receiving this because…" footers. Sanitization mirrors `text` (allows `<a>` / `<strong>` / `<em>` / `<b>` / `<i>`).
+- **`info_row(label, value)`** — label/value row using the email-safe two-column table pattern Stripe / Linear / Square / Resend converge on for transactional info cards: muted label on the left, dark right-aligned value on the right, 1px hairline at the bottom. Use this when the LABEL is supporting context and the VALUE is the primary content (`Plan - Pro`, `Status - Active`). The existing `price_row` (centered, both sides equal weight) stays the right tool for receipt-style line items.
+- **`attach(filename, content, mime_type:, inline:)`** — adds a binary attachment to the outgoing message. `content` accepts raw bytes OR a filesystem path (when the string matches an existing file, it's read for you). Pass `inline: true` to send the part with `Content-Disposition: inline`; prefer `inline_image` when you also want Goodmail to emit the matching `cid:` image tag.
+- **`inline_image(filename, content, alt:, width:, height:, mime_type:)`** — convenience helper that registers an inline-disposition attachment AND emits the matching `<img src="cid:...">` tag at that point in the email body. Use when you need the image to travel with the email (no public hosting, offline reading, archival contexts); when you have a public URL prefer `image(src, alt)` — it's lighter on the wire.
+
+#### Inline emphasis tags allowed in `text`
+- `<strong>`, `<em>`, `<b>`, and `<i>` now pass through the `text(string)` sanitizer alongside `<a>`. Previously these were silently stripped, so copy like `text "<strong>Important:</strong> read the receipt"` rendered as plain `Important: read the receipt`. All four tags are universally supported in every modern email client and add no layout risk to the table-based template.
+
+#### `Goodmail.render` parts struct
+- `EmailParts` now carries an `attachments` field (in addition to `html` and `text`) populated with everything the DSL block registered via `attach` / `inline_image`. Inline descriptors include the generated `content_id` that matches the `cid:` URL emitted into the HTML.
+
+#### Action Mailer integration helpers
+- **Zero-include Action Mailer helpers.** When Goodmail loads, it installs private `goodmail_mail(...) { ... }`, `goodmail_render_parts(...) { ... }`, and `goodmail_mail_parts(parts, headers, unsubscribe_url:)` helpers on `ActionMailer::Base`. Custom mailers, Devise mailers, Pay mailers, and app-specific wrappers can use them without per-class include boilerplate. The helpers keep mailer instance variables/private helpers available inside DSL blocks, support render-only `locale:`, fan attachments into Action Mailer, pin inline Content-IDs, strip Goodmail-only headers before `mail()`, and add RFC 8058-correct unsubscribe headers.
+- **Per-render configuration overrides.** `Goodmail.compose`, `Goodmail.render`, `goodmail_mail`, and `goodmail_render_parts` accept `config: { ... }` for tenant / product whitelabel emails. Overrides are scoped to the current render via a thread-local config and do not mutate process-wide `Goodmail.config`, so concurrent mail deliveries cannot bleed one product's branding into another's email.
+- **Action Mailer header passthrough.** `Goodmail.compose` and the auto-installed mailer helpers now forward Action Mailer's normal header surface (`date:`, `return_path:`, delivery options, custom `"X-..."` headers, etc.) after stripping only Goodmail render options. This follows Rails' own `mail` behavior instead of maintaining a narrow Goodmail whitelist.
+
+#### Test suite
+- **253 tests, 913 assertions, 100% line coverage** across the Ruby source. The gem previously had no tests of its own; the README's `rake spec` instruction was aspirational. Run with `rake test`; gate SimpleCov instrumentation on `COVERAGE=1 rake test`.
+
+### Fixed
+
+#### Deliverability + headers
+- **RFC 8058 one-click unsubscribe.** Goodmail now sets `List-Unsubscribe-Post: List-Unsubscribe=One-Click` alongside the existing `List-Unsubscribe` header when the unsubscribe URL is HTTPS, matching RFC 8058's HTTPS URI requirement. Non-HTTPS unsubscribe URLs still get the classic `List-Unsubscribe` header, but Goodmail no longer advertises one-click POST support for URLs that are not eligible. Gmail's and Yahoo's [Feb 2024 sender requirements](https://support.google.com/mail/answer/81126) treat missing one-click support as a spam signal for eligible bulk senders. Existing applications with HTTPS unsubscribe URLs inherit the fix on upgrade; make sure the final sender/provider DKIM-signs these headers, since Goodmail can only set them before delivery.
+
+#### Plaintext quality
+The plaintext part of every multipart message had four classes of artifact that surfaced after running real emails through Mailcatcher. Each one would silently degrade quality for recipients on text-only clients (CLI mail, accessibility tooling, spam filters that judge from the plaintext part):
+
+- **Preheader no longer leaks as a phantom first line.** The layout's hidden inbox-preview `<span style="display:none">` was being extracted to plaintext by Premailer (which doesn't honor `display:none`), opening every email with a duplicate intro the recipient was never supposed to see in the body. The preheader span is now stripped from the source HTML before plaintext extraction, matched by its specific `display:none + font-size:1px` signature so legitimate hidden spans elsewhere are preserved.
+- **Button labels no longer appear twice.** `button` emits both a `<v:roundrect>` (Outlook VML, inside `<!--[if mso]>...<![endif]-->`) AND a regular `<a>`. Premailer ignores conditional comments and was extracting text from BOTH, so plaintext got the label twice (once bare from the VML's `<center>label</center>`, once with the URL from `<a href>label</a>`). The MSO conditional blocks are now stripped from the source HTML before plaintext extraction.
+- **Stray `CompanyName` line from inline image alt is gone.** `image` / `inline_image` calls without an explicit alt fall back to `config.company_name` (so screen readers have something to read). Premailer extracted that alt verbatim into plaintext, leaving a bare-company-name line floating next to every embedded image. The cleanup pass now strips standalone lines that exactly match the company name; legitimate uses embedded in sentences are preserved untouched.
+- **`info_row` flattens to the conventional `Label: Value` shape in plaintext.** A two-cell `<table>` previously extracted as two separate lines (`Label\nValue`) — correct table extraction, but a worse plaintext UX than the colon-form every modern transactional sender uses. The HTML side keeps the visible two-cell table.
+
+#### Encoding
+- **HTML + plaintext: accented characters / Unicode no longer get double-encoded.** Premailer's libxml2 backend was defaulting to Latin-1 when no `<meta charset>` tag was present in the source HTML, mangling every UTF-8 character (`Duración` → `Duración`, `€` → `â¬`). All Premailer calls now pin `input_encoding: "UTF-8"`. The shipped layout already declares the meta charset; this fix protects custom `layout_path:` callers that don't.
+
+#### Inline images
+- **`inline_image` now produces an `<img>` that actually renders.** Mail gem auto-generates a globally-unique Content-ID (`<longhash@host.tld.mail>`) for every attachment, but the DSL must write the `<img src="cid:...">` before Action Mailer materializes the attachment. Goodmail now generates an RFC 2392-shaped Content-ID in the Builder, emits that exact `cid:` URL in the HTML, and pins the inline Mail part to the same ID so the body's reference resolves.
+- **`attach` / `inline_image` no longer crash on binary content.** The path-or-bytes resolver was calling `File.file?` on the string unconditionally, and `File.file?` raises `ArgumentError: path name contains null byte` on any String containing `\0` — exactly what binary file content (PNG / PDF / .ics) routinely contains. The resolver now short-circuits when the string contains a NUL byte or exceeds typical PATH_MAX (4096 bytes), so the documented `inline_image("logo.png", png_bytes)` shape works as advertised.
+- **Duplicate inline filenames raise `Goodmail::Error` at registration time.** Inline descriptors are still keyed by filename when custom `Goodmail.render` callers fan them into Action Mailer's attachments hash, so duplicate inline filenames are ambiguous even though Goodmail generates distinct Content-IDs. We now fail loud at the DSL with an actionable error. Non-inline `attach` with duplicate filenames is still allowed (it's a UX wart but not a rendering bug — recipients see two files with the same name).
+
+#### Visual tweak
+- **Buttons no longer force `text-transform: capitalize`.** The default styling now preserves the EXACT casing the caller wrote — a button labeled `view receipt` renders as `view receipt`, not `View Receipt`; `OPEN` stays `OPEN`. The previous default was opinionated and broke acronyms, all-lowercase casual copy, and i18n cases where capitalization rules differ from English (German nouns, Spanish proper nouns following articles).
+
+### Internal
+- Replaced the `case heading_tag` style lookup inside `Builder`'s `define_method` heading definer with a frozen `HEADING_STYLES` constant. The previous shape carried an unreachable `else` clause that no test could cover by construction; the replacement is shorter, faster (one hash lookup per heading), and exhaustive by definition.
+- Extracted plaintext generation into `Goodmail::Plaintext`. Both `Goodmail::Email.render` and `Goodmail::Mailer#compose_message` previously had their own copies of the cleanup pipeline; consolidating into one module makes plaintext quality testable in one place and prevents future drift between the two paths.
+- `Goodmail.compose` now renders through `Goodmail.render` once, then passes already inlined HTML, cleaned plaintext, and attachment descriptors into the internal Action Mailer action. This removes the duplicate Premailer/plaintext path from `Goodmail::Mailer` while preserving Action Mailer's lazy `MessageDelivery` handoff.
+- `ostruct` declared as an explicit runtime dependency. Goodmail requires it directly (configuration is backed by `OpenStruct`); Ruby 3.4 prints a deprecation warning when ostruct is loaded from the standard library, and Ruby 3.5 removes it from the default gems set entirely.
+
+### Meta
+- Standardized the testing scaffolding to match the convention shared with the surrounding Ruby gems:
+  - `.simplecov` config file (auto-loaded; SimpleFormatter, branch coverage enabled, minimum thresholds, custom at_exit summary).
+  - `Gemfile` with `:development` / `:development, :test` groups (minitest ~> 6.0, minitest-mock, minitest-reporters, simplecov, rubocop + rubocop-minitest + rubocop-performance).
+  - `Rakefile` using `bundler/gem_tasks` + `Rake::TestTask`; `rake test` runs the suite with the canonical Minitest::Reporters output and emits the coverage summary at the end.
+  - `.rubocop.yml` shared cop set + thresholds (style/layout/metrics overrides matching the other gems).
+  - `.github/workflows/test.yml` matrix tests across Ruby 3.3, 3.4, and 4.0.
+  - `.github/workflows/claude.yml` and `.github/workflows/claude-code-review.yml` for Claude Code automation parity.
+  - `goodmail.gemspec` no longer carries development dependencies — they all live in the Gemfile groups, same as the sibling gems.
+
+## [0.3.1] - 2026-02-25
+- Maintenance release. Documentation alignment (example mailers
+  follow the `Goodmailer` suffix convention) and a configuration
+  alias (`Goodmail.configuration` ≡ `Goodmail.config`). No public
+  API changes.
+
+## [0.3.0] - 2025-05-15
+- Add Goodmail.render for custom mailers
+
 ## [0.2.0] - 2025-05-02
 
 ### Added

data/README.md

@@ -9,7 +9,7 @@ Goodmail turns your ugly, default, text-only emails into SaaS-ready emails. It's
 
 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.
+Here's the catch: Goodmail gives you one opinionated default template. You can override the layout for advanced cases, but the happy path is deliberately narrow: no templates, no partials, and no styling decisions for every transactional email. 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!)
 
@@ -106,7 +106,7 @@ mail = Goodmail.compose(
   to: recipient.email,
   from: "'#{Goodmail.config.company_name} Support' <support@myapp.com>",
   subject: "Welcome to MyApp!",
-  preheader: "Your adventure begins now!" # Optional override
+  preheader: "Your account is ready." # Optional override
 ) do
   h1 "Welcome aboard, #{recipient.name}!"
   text "We're thrilled to have you join the MyApp community."
@@ -134,6 +134,17 @@ mail.deliver_later
 
 *(Requires Active Job configured.)*
 
+`Goodmail.compose` returns a normal `ActionMailer::MessageDelivery`. Pass the
+same headers you would pass to Action Mailer's `mail()` (`reply_to:`,
+`date:`, `return_path:`, custom `"X-..."` headers, delivery options, etc.);
+Goodmail strips only its own render options before handing the message to
+Action Mailer.
+
+For real Rails mailer classes, prefer the auto-installed `goodmail_mail`
+helper shown below. It keeps the work inside the mailer action, preserves
+Action Mailer's lazy `MessageDelivery` / `deliver_later` model, and avoids
+manual `Goodmail.render(..., context: self)` glue.
+
 ## Why does `goodmail` exist?
 
 Here's the problem: you can't just use standard HTML and CSS in mails.
@@ -162,77 +173,169 @@ Inside the `Goodmail.compose` block, you have access to these methods:
 
 *   `h1(text)`, `h2(text)`, `h3(text)`: Styled heading tags.
 *   `text(string)`: A paragraph of text. Allows simple inline `<a>` tags with `href` attributes; other HTML is stripped for safety. Handles `\n` for line breaks.
+*   `link(link_text, url)`: An inline styled link, rendered in the configured `brand_color`. Cleaner than hand-writing `<a>` tags inside `text` blocks when the whole paragraph is the link.
+*   `small(string)`: A small grey paragraph for fine print, legal disclaimers and "you are receiving this because…" footers.
 *   `button(link_text, url)`: A prominent, styled call-to-action button (includes Outlook VML fallback).
 *   `image(src, alt = "", width: nil, height: nil)`: Embeds an image, centered by default (includes Outlook MSO fallback). Uses `config.company_name` for alt text if none provided.
+*   `attach(filename, content, mime_type: nil, inline: false)`: Attaches a binary file (PDF, .ics, .csv, image…) to the outgoing email. `content` can be raw bytes or a filesystem path — when the string matches an existing file it is read for you. Pass `inline: true` to send the part with `Content-Disposition: inline`; prefer `inline_image` when you also want Goodmail to emit the matching `cid:` image tag.
+*   `inline_image(filename, content, alt: "", width: nil, height: nil, mime_type: nil)`: Convenience helper that registers an inline-disposition attachment AND emits the matching `<img src="cid:...">` tag at that point in the email body. Use when you need the image to travel with the email (no public hosting available, offline reading, etc.); when you already have a public URL prefer `image(src, alt)` — it's lighter on the wire.
 *   `space(pixels = 16)`: Adds vertical whitespace.
 *   `line`: Adds a horizontal rule (`<hr>`).
 *   `center { ... }`: Centers the content generated within the block.
 *   `code_box(text)`: Displays text centered and bold within a styled box (grey background, padding, italic). Text is HTML-escaped.
-*   `price_row(name, price)`: Adds a styled paragraph showing a name and price, separated by a top border (e.g., for simple receipt line items). Text is HTML-escaped.
+*   `price_row(name, price)`: Adds a styled paragraph showing a name and price, separated by a top border (e.g., for simple receipt line items). Both the name and the price render bold and centered — meant for cases where label and amount carry equal weight. Text is HTML-escaped.
+*   `info_row(label, value)`: Adds a label/value row using the email-safe two-column table pattern (muted label on the left, dark right-aligned value on the right, 1px hairline at the bottom). Use this when the LABEL is supporting context and the VALUE is the primary content ("Plan - Pro", "Status - Active"). Stack multiple consecutive `info_row` calls to build a clean info card. Text is HTML-escaped.
 *   `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.
 
+### Rails Mailers: Use `goodmail_mail`
+
+When Goodmail is loaded, Rails mailers get three private helpers automatically:
+`goodmail_mail` for the common render-and-send path, and
+`goodmail_render_parts` + `goodmail_mail_parts` when you need to render first.
+
+```ruby
+# In your custom mailer, including framework overrides such as Devise or Pay
+
+# Define your headers (to, from, subject, etc.)
+# You can pass :unsubscribe_url, :preheader, :locale, :config /
+# :configuration, and :layout_path in the same hash. Goodmail uses them for
+# rendering and strips them before calling Action Mailer's mail().
+class NotificationMailer < ApplicationMailer
+  def important_update(recipient)
+    details_url = view_details_url(recipient)
+
+    goodmail_mail(
+      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
+    ) do
+      h1 "Hello, #{recipient.name}!"
+      text "This is an important update regarding your account."
+      button "View Details", details_url
+      sign "The MyApp Team"
+    end
+  end
+end
+```
+
+`goodmail_mail` renders the DSL, strips Goodmail-only keys before calling
+Action Mailer's `mail()`, applies `attach` / `inline_image` parts, pins inline
+Content-IDs, and adds the correct `List-Unsubscribe` headers.
+Any normal Action Mailer header you pass (`date:`, `return_path:`,
+`delivery_method:`, `"X-Custom"`, etc.) is forwarded to `mail()`; only
+Goodmail render options such as `preheader:`, `unsubscribe_url:`, `locale:`,
+`context:`, `config:` / `configuration:`, and `layout_path:` are removed from
+the wire headers.
+The block keeps normal mailer context: instance variables and private mailer
+helpers are available, and `locale:` wraps the DSL block in `I18n.with_locale`.
+
+Framework mailers can also pass their native header hash directly. For example,
+a Devise override can keep Devise's own `headers_for(...)` output as the single
+source of truth and let Goodmail handle only the body/render mechanics:
+
+```ruby
+class DeviseGoodmailer < Devise::Mailer
+  def confirmation_instructions(record, token, opts = {})
+    @token = token
+    initialize_from_record(record)
+
+    goodmail_mail(headers_for(:confirmation_instructions, opts), locale: record.locale) do
+      text "Confirm your account below."
+      button "Confirm my account", confirmation_url(record, confirmation_token: token)
+      sign
+    end
+  end
+end
+```
+
 ### 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.
+For advanced use cases where 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.
+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 an `ActionMailer::MessageDelivery` ready for delivery, it returns a `Goodmail::EmailParts` struct.
 
-The `Goodmail::EmailParts` struct (defined in `goodmail/email.rb`) has two attributes:
+The `Goodmail::EmailParts` struct (defined in `goodmail/email.rb`) has three attributes:
 *   `html`: The final, inlined HTML content for your email.
 *   `text`: The cleaned-up plain text version of your email.
+*   `attachments`: An array of `{ filename:, content:, mime_type:, inline:, content_id: }` hashes for every `attach` / `inline_image` call inside the DSL block. Empty array when the DSL didn't register any attachments. `content_id` is present for inline attachments and already matches any `cid:` URL emitted by `inline_image`. `goodmail_mail` / `goodmail_render_parts` / `goodmail_mail_parts` hand these descriptors to Action Mailer for you.
 
-**How to use it:**
-
-You can then use these parts within any Action Mailer setup:
+If you truly need to render first because another step must inspect or mutate
+the generated parts before sending, use the lower-level helpers:
 
 ```ruby
-# In your custom mailer (e.g., a Devise mailer override)
+class CustomMailer < ApplicationMailer
+  def custom_message(recipient)
+    render_options = {
+      subject: "Important Update",
+      unsubscribe_url: custom_unsubscribe_url_for_user(recipient),
+      preheader: "A quick update you should see."
+    }
+
+    parts = goodmail_render_parts(render_options) do
+      text "Rendered separately."
+      inline_image "logo.png", logo_bytes, mime_type: "image/png"
+    end
 
-# 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"
+    goodmail_mail_parts(
+      parts,
+      to: recipient.email,
+      from: "notifications@myapp.com",
+      subject: render_options[:subject],
+      unsubscribe_url: render_options[:unsubscribe_url]
+    )
+  end
 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)
+**Key Differences from `Goodmail.compose`:**
 
-# 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
+*   **Return Value**: `Goodmail.render` returns an instance of `Goodmail::EmailParts` (e.g., `EmailParts.new(html: "...", text: "...")`). `Goodmail.compose` returns an `ActionMailer::MessageDelivery`.
+*   **Purpose**: `Goodmail.render` is primarily for generating and retrieving processed email content parts. `Goodmail.compose` is for generating a complete, deliverable Action Mailer message.
+*   **Lazy delivery model**: `Goodmail.compose` evaluates the Ruby DSL block before returning the `ActionMailer::MessageDelivery`, then passes already rendered HTML, plaintext, and attachment descriptors into Goodmail's internal mailer action. Ruby blocks are not Active Job-serializable, so this is the right one-shot API. For fully native Action Mailer action execution in app mailers, use `goodmail_mail` inside the mailer method.
+*   **List-Unsubscribe Headers**: `Goodmail.render` itself does *not* add the `List-Unsubscribe` or `List-Unsubscribe-Post` headers to any mail object (as it doesn't create one). The auto-installed Action Mailer helpers add them when you call `goodmail_mail` / `goodmail_mail_parts`; they set one-click `List-Unsubscribe-Post` only for HTTPS URLs. Gmail's and Yahoo's [bulk-sender requirements](https://support.google.com/mail/answer/81126) treat missing one-click unsubscribe support as a spam signal for eligible bulk senders. Your delivery stack must also DKIM-sign the unsubscribe headers; Goodmail can set the headers, but the final sender/provider controls the signature.
+*   **Attachments + inline images**: `Goodmail.render` collects every `attach` / `inline_image` call into `parts.attachments`. The auto-installed Action Mailer helpers fan those descriptors into Action Mailer's attachments hash and pins inline Content-IDs for you. `Goodmail.compose` handles both internally.
+*   **Per-message branding**: pass `config: { company_name:, logo_url:, brand_color:, footer_text: }` to `Goodmail.compose`, `Goodmail.render`, `goodmail_mail`, or `goodmail_render_parts` for tenant / product whitelabel emails. The override is scoped to that render in the current thread, so apps do not need to mutate global `Goodmail.config` around a delivery.
+
+### Integrating with the Pay Gem
+
+Goodmail works seamlessly with the [Pay gem](https://github.com/pay-rails/pay) to send beautiful transactional emails for payment notifications (receipts, refunds, subscription updates, etc.).
+
+Since Pay allows you to configure a custom mailer class, you can create a mailer that uses Goodmail's auto-installed helpers to generate beautiful email content for all Pay notifications.
 
-# The `final_mail_object` returned by ActionMailer can then be delivered:
-# final_mail_object.deliver_now or final_mail_object.deliver_later
+In the examples below, app-defined mailers that use Goodmail follow the `*Goodmailer` suffix convention. This is just a naming convention for clarity, not a requirement imposed by Goodmail itself.
+
+**Quick Setup:**
+
+1. Copy the example mailer from [`examples/pay_goodmailer.rb`](examples/pay_goodmailer.rb) to your Rails app at `app/mailers/pay_goodmailer.rb`
+
+2. Configure Pay to use the custom mailer in `config/initializers/pay.rb`:
+
+```ruby
+Pay.setup do |config|
+  config.parent_mailer = "ApplicationMailer"
+  config.mailer = "PayGoodmailer"
+  # ... other Pay configuration
+end
 ```
 
-**Key Differences from `Goodmail.compose`:**
+3. Customize the email content and URLs in the mailer to match your app
 
-*   **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.
+The example implementation includes all Pay notification types:
+- `receipt` - Payment receipts
+- `refund` - Refund confirmations
+- `subscription_renewing` - Renewal reminders
+- `payment_action_required` - Payment action needed
+- `subscription_trial_will_end` - Trial ending soon
+- `subscription_trial_ended` - Trial has ended
+- `payment_failed` - Failed payment alerts
+
+Each method uses `goodmail_mail(pay_mail_arguments, ...)` so Pay-specific
+recipient/header setup stays in the app while Goodmail owns rendering,
+attachments, multipart assembly, and unsubscribe headers.
 
 ### Adding Unsubscribe Functionality
 
@@ -249,7 +352,7 @@ Goodmail helps you add the `List-Unsubscribe` header and an optional visible lin
       # ... other headers ...
     ) do # ...
     ```
-    *If an `unsubscribe_url` is provided, Goodmail adds the `List-Unsubscribe` header.*
+    *If an `unsubscribe_url` is provided, Goodmail adds the `List-Unsubscribe` header. If that URL is HTTPS, Goodmail also adds the RFC 8058 `List-Unsubscribe-Post: List-Unsubscribe=One-Click` header. Gmail's and Yahoo's [bulk-sender requirements](https://support.google.com/mail/answer/81126) (Feb 2024+) treat missing one-click unsubscribe as a spam signal for eligible bulk senders. Your HTTPS endpoint should accept a POST body of `List-Unsubscribe=One-Click`, complete the unsubscribe without another confirmation step, and avoid redirects. Your sender/provider must DKIM-sign the unsubscribe headers for mailbox providers to trust one-click support.*
 
 2.  **Optionally Show Footer Link:**
     *   Set `config.show_footer_unsubscribe_link = true`.
@@ -268,7 +371,9 @@ Goodmail helps you add the `List-Unsubscribe` header and an optional visible lin
 
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the test suite (Minitest 6+, no Rails app required — every code path is exercised in isolation through `Goodmail.compose` / `Goodmail.render`). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To check line coverage, run `COVERAGE=1 rake test`. The suite ships with 100% line coverage as a baseline; if you add a method, add a test for it.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 

data/Rakefile

@@ -1,4 +1,15 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  # Silence noisy stdlib warnings (e.g. ostruct deprecation notice in
+  # Ruby 3.4) so the run output stays focused on real test failures.
+  t.warning = false
+end
+
+task default: :test

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/goodmail",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}