Add README

Author: bradgessler

Gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: .
   specs:
     supermail (0.1.0)
+      mail (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
@@ -13,6 +14,21 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
+    mail (2.8.1)
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    mini_mime (1.1.5)
+    net-imap (0.5.6)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
@@ -38,6 +54,7 @@ GEM
       rspec-support (~> 3.13.0)
     rspec-support (3.13.2)
     stringio (3.1.6)
+    timeout (0.4.3)
 
 PLATFORMS
   arm64-darwin-24

README.md

@@ -1,28 +1,87 @@
 # Supermail
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/supermail`. To experiment with that code, run `bin/console` for an interactive prompt.
+Supermail is a slightly more intuitive way of organizing Emails in a Rails application.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add supermail
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Then install it in Rails.
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+rails generate supermail:install
+```
+
+This creates the `app/emails/application_email.rb` file that you can customize as the base for all emails.
+
+```ruby
+class ApplicationEmail < Supermail::Email
+  def from = "Supermail <noreply@supermail.com>"
+
+  class HTML
+    def after_template
+      p { "Best, The Supermail Team" }
+    end
+  end
+
+  class Text
+    def after_template
+      "Best,\nThe Supermail Team"
+    end
+  end
+end
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+To generate a new email, run the following command:
+
+```bash
+rails generate supermail:email User::Welcome
+```
+
+This will create a new email class in `app/mailers/user/welcome.rb`.
+
+```ruby
+# ./app/email/user/welcome.rb
+class User::Welcome < ApplicationEmail
+  def initialize(user:)
+    @user = user
+  end
+
+  def subject = "Welcome to Supermail!"
+
+  class HTML
+    def view_template
+      h1 { "Welcome, #{@user.name}!" }
+      p { "We're excited to have you on board." }
+    end
+  end
+
+  class Text
+    def view_template
+      "Welcome, #{@user.name}!\n\nWe're excited to have you on board."
+    end
+  end
+end
+```
+
+Then, to send the email.
+
+```ruby
+User::Welcome.new(user: User.first).deliver_now
+```
+
+If you want to tweak the message on the fly, you can modify the message, then deliver it.
+
+```ruby
+User::Welcome.new(user: User.first).message.tap do
+  it.to << "another@example.com"
+end.deliver_now
 
 ## Development
 
@@ -32,4 +91,4 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/supermail.
+Bug reports and pull requests are welcome on GitHub at https://github.com/rubymonolith/supermail.

lib/supermail.rb

@@ -2,7 +2,84 @@
 
 require_relative "supermail/version"
 
+require 'mail'
+require "supermail/version"
+
 module Supermail
   class Error < StandardError; end
-  # Your code goes here...
+
+  # A simple Email builder that wraps Mail::Message
+  class Email
+    # Hook to ensure default initialization runs before any subclass initialize
+    module Defaults
+      def initialize(*args, &block)
+        # default fields
+        @cc = []
+        @bcc = []
+        @headers = {}
+        @attachments = []
+        super
+      end
+    end
+
+    # Whenever subclassing, prepend Defaults to ensure it wraps initialize
+    def self.inherited(subclass)
+      subclass.prepend Defaults
+      super
+    end
+
+    attr_accessor :from, :to, :cc, :bcc, :subject,
+                  :reply_to, :return_path, :date, :message_id,
+                  :in_reply_to, :references, :headers,
+                  :text_body, :html_body, :attachments
+
+    # Builds a Mail::Message from this Email's attributes
+    # @return [Mail::Message]
+    def message
+      mail = Mail.new
+      mail.from        = Array(from) if from
+      mail.to          = Array(to)
+      mail.cc          = cc if cc.any?
+      mail.bcc         = bcc if bcc.any?
+      mail.reply_to    = Array(reply_to) if reply_to
+      mail.return_path = return_path if return_path
+      mail.date        = date if date
+      mail.message_id  = message_id if message_id
+      mail.in_reply_to = in_reply_to if in_reply_to
+      mail.references  = references if references
+
+      # Custom headers
+      headers.each { |key, value| mail.header[key] = value }
+
+      mail.subject = subject if subject
+
+      # Bodies
+      if text_body
+        mail.text_part = Mail::Part.new do
+          body text_body
+        end
+      end
+
+      if html_body
+        mail.html_part = Mail::Part.new do
+          content_type 'text/html; charset=UTF-8'
+          body html_body
+        end
+      end
+
+      # Attachments (each as a hash: { filename:, content: })
+      attachments.each do |att|
+        mail.add_file filename: att[:filename], content: att[:content]
+      end
+
+      mail
+    end
+
+    # Delivers the built Mail::Message via its configured delivery_method
+    # @return [Mail::Message]
+    def deliver
+      raise Error, "`to` address is required" unless to
+      message.deliver!
+    end
+  end
 end

spec/supermail_spec.rb

@@ -1,11 +1,19 @@
 # frozen_string_literal: true
 
-RSpec.describe Supermail do
+RSpec.describe Supermail::Email do
   it "has a version number" do
     expect(Supermail::VERSION).not_to be nil
   end
 
-  it "does something useful" do
-    expect(false).to eq(true)
+  let(:email) { Supermail::Email.new }
+  before do
+    email.to = "user@example.com"
+    email.subject = "Hello"
+  end
+
+  describe "#to" do
+    it "returns email address" do
+      expect(email.to).to eq("user@example.com")
+    end
   end
 end

supermail.gemspec

@@ -8,16 +8,16 @@ Gem::Specification.new do |spec|
   spec.authors = ["Brad Gessler"]
   spec.email = ["bradgessler@gmail.com"]
 
-  spec.summary = "TODO: Write a short summary, because RubyGems requires one."
-  spec.description = "TODO: Write a longer description or delete this line."
-  spec.homepage = "TODO: Put your gem's website or public repo URL here."
+  spec.summary = "Build emails with plain ol' Ruby objects."
+  spec.description = spec.summary
+  spec.homepage = "https://github.com/rubymonolith/supermail"
   spec.required_ruby_version = ">= 3.1.0"
 
-  spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
-  spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = spec.homepage
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
-  # spec.add_dependency "example-gem", "~> 1.0"
+  spec.add_dependency "mail", "~> 2.0"
 
   # For more information and examples about making a new gem, check out our
   # guide at: https://bundler.io/guides/creating_gem.html