courrier 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 394bb78e24569d93855f2bcf788662ec8773371779b7743c5737867b893d4b38
+  data.tar.gz: 4f35baf4f3ccca75ac05cd6bc7140f2eb4585c0c95e528f1aa45bc1227ec3777
+SHA512:
+  metadata.gz: 387e9a879abac10ecbd97ac1a254fb08c40e48e8faf1a37f3a284dd2efd118dd70e0bf1d0032d3318914b2ddaa9242a56495547c6599dc3483844b3449114846
+  data.tar.gz: f5b458d0cc5ff6f640f0e3ffc19be8e0e6982721dcd4ff29a3dc49d42e7a3d6e9e6b0ba2d132e8f75d2a6c5edb8f6d2ae581b3076027fc9a5a48207c54ecc2ec

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development do
+  gem "standard", "~> 1.49"
+end
+
+group :development, :test do
+  gem "rake", "~> 13.2", ">= 13.2.1"
+  gem "minitest", "~> 5.25", ">= 5.25.5"
+  gem "debug", "~> 1.9", ">= 1.9.2"
+end

data/Gemfile.lock

@@ -0,0 +1,109 @@
+PATH
+  remote: .
+  specs:
+    courrier (0.5.0)
+      launchy (>= 3.1, < 4)
+      nokogiri (>= 1.18, < 2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.3)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    date (3.4.1)
+    debug (1.10.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    json (2.11.1)
+    language_server-protocol (3.17.0.4)
+    launchy (3.1.1)
+      addressable (~> 2.8)
+      childprocess (~> 5.0)
+      logger (~> 1.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    nokogiri (1.18.8-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.18.8-x86_64-linux-gnu)
+      racc (~> 1.4)
+    parallel (1.27.0)
+    parser (3.3.8.0)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.4.0)
+    psych (5.2.3)
+      date
+      stringio
+    public_suffix (6.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    rdoc (6.13.1)
+      psych (>= 4.0.0)
+    regexp_parser (2.10.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rubocop (1.75.3)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.44.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.44.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    rubocop-performance (1.25.0)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.38.0, < 2.0)
+    ruby-progressbar (1.13.0)
+    standard (1.49.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.75.2)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.8.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.25.0)
+    stringio (3.1.7)
+    unicode-display_width (3.1.4)
+      unicode-emoji (~> 4.0, >= 4.0.4)
+    unicode-emoji (4.0.4)
+
+PLATFORMS
+  arm64-darwin-23
+  x86_64-darwin-23
+  x86_64-linux
+
+DEPENDENCIES
+  courrier!
+  debug (~> 1.9, >= 1.9.2)
+  minitest (~> 5.25, >= 5.25.5)
+  rake (~> 13.2, >= 13.2.1)
+  standard (~> 1.49)
+
+BUNDLED WITH
+   2.6.8

data/README.md

@@ -0,0 +1,243 @@
+# Courrier
+
+Modern, API-powered email delivery for Ruby apps.
+
+```ruby
+# Quick example
+OrderEmail.deliver to: "recipient@railsdesigner.com"
+```
+
+<a href="https://railsdesigner.com/" target="_blank">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Rails-Designer/courrier/HEAD/.github/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Rails-Designer/courrier/HEAD/.github/logo-light.svg">
+    <img alt="Rails Designer logo" src="https://raw.githubusercontent.com/Rails-Designer/courrier/HEAD/.github/logo-light.svg" width="240" style="max-width: 100%;">
+  </picture>
+</a>
+
+**Sponsored By [Rails Designer](https://railsdesigner.com/)**
+
+
+## Installation
+
+Add the gem:
+```bash
+bundle add courrier
+```
+
+Generate the configuration file:
+```bash
+bin/rails generate courrier:install
+```
+
+This creates `config/initializers/courrier.rb` for configuring email providers and default settings.
+
+
+## Usage
+
+Generate a new email:
+```bash
+bin/rails generate courrier:email Order
+```
+```ruby
+class OrderEmail < Courrier::Email
+  def subject = "Here is your order!"
+
+  def text
+    <<~TEXT
+      text body here
+    TEXT
+  end
+
+  def html
+    <<~HTML
+      html body here
+    HTML
+  end
+end
+```
+💡 Write your email content using the [Minimal Email Editor](https://railsdesigner.com/minimal-email-editor/).
+
+
+## Configuration
+
+Courrier uses a configuration system with three levels (from lowest to highest priority):
+
+1. **Global configuration**
+```ruby
+Courrier.configure do |config|
+  config.provider = "postmark"
+  config.api_key = "xyz"
+  config.from = "devs@railsdesigner.com"
+  config.default_url_options = { host: "railsdesigner.com" }
+
+  # Provider-specific configuration
+  config.providers.loops.transactional_id = "default-template"
+  config.providers.mailgun.domain = "notifications.railsdesigner.com"
+end
+```
+
+2. **Email class defaults**
+```ruby
+class OrderEmail < Courrier::Email
+  configure from: "devs@railsdesigner.com",
+            cc: "records@railsdesigner.com",
+            provider: "mailgun",
+end
+```
+
+3. **Instance options**
+```ruby
+OrderEmail.deliver to: "recipient@railsdesigner.com",\
+                   from: "devs@railsdesigner.com",\
+                   provider: "sendgrid",\
+                   api_key: "sk_a1b1c3"
+```
+
+
+## Providers
+
+Courrier supports these transactional email providers:
+
+- [Loops](https://loops.so)
+- [Mailgun](https://mailgun.com)
+- [Mailjet](https://mailjet.com)
+- [MailPace](https://mailpace.com)
+- [Postmark](https://postmarkapp.com)
+- [SendGrid](https://sendgrid.com)
+- [SparkPost](https://sparkpost.com)
+
+⚠️ Some providers still need manual verification of their implementation. If you're using one of these providers, please help verify the implementation by sharing your experience in [this GitHub issue](https://github.com/Rails-Designer/courrier/issues/4). 🙏
+
+
+## More Features
+
+Additional functionality to help with development and email handling:
+
+
+### Email Preview
+
+Preview emails in your browser during development:
+```ruby
+
config.provider = "preview" # Opens emails in your default browser
+```
+
+
Previews are automatically cleared with `bin/rails tmp:clear`, or manually with `bin/rails courrier:clear`.
+
+
+### Layout Support
+
+Wrap your email content using layouts:
+```ruby
+class OrderEmail < Courrier::Email
+ layout text: "%{content}\n\nThanks for your order!",
+        html: "<div>\n%{content}\n</div>"
+end
+```
+
+Using a method:
+```ruby
+class OrderEmail < Courrier::Email
+  layout html: :html_layout
+
+  def html_layout
+    <<~HTML
+      <div style='font-family: ui-sans-serif, system-ui;'>
+        %{content}
+      </div>
+    HTML
+  end
+end
+```
+
+Using a separate class:
+```ruby
+class OrderEmail < Courrier::Email
+  layout html: OrderLayout
+end
+
+class OrderLayout
+  self.call
+    <<~HTML
+      <div style='font-family: ui-sans-serif, system-ui;'>
+        %{content}
+      </div>
+    HTML
+  end
+end
+```
+
+
+### Auto-generate Text from HTML
+
+Automatically generate plain text versions from your HTML emails:
+```ruby
+
config.auto_generate_text = true # Defaults to false
+```
+
+
+### Email Address Helper
+
+Compose RFC 2822-compliant email addresses with display names:
+```ruby
+class SignupsController < ApplicationController
+  def create
+    recipient = email_with_name("devs@railsdesigner.com", "Rails Designer Devs")
+
+    WelcomeEmail.deliver to: recipient
+  end
+end
+```
+
+In Plain Ruby Objects:
+```ruby
+class Signup
+  include Courrier::Email::Address
+
+  def send_welcome_email(user)
+    recipient = email_with_name(user.email_address, user.name)
+
+    WelcomeEmail.deliver to: recipient
+  end
+end
+```
+
+
+### Logger Provider
+
+Use Ruby's built-in Logger for development and testing:
+
+```ruby
+config.provider = "logger" # Outputs emails to STDOUT
+config.logger = custom_logger # Optional: defaults to ::Logger.new($stdout)
+```
+
+### Custom Providers
+
+Create your own provider by inheriting from `Courrier::Email::Base`:
+```ruby
+class CustomProvider < Courrier::Email::Base
+  ENDPOINT_URL = ""
+
+  def body = ""
+
+  def headers = ""
+end
+```
+
+Then configure it:
+```ruby
+config.provider = "CustomProvider"
+```
+
+Check the [existing providers](https://github.com/Rails-Designer/courrier/tree/main/lib/courrier/email/providers) for implementation examples.
+
+
+## Contributing
+
+This project uses [Standard](https://github.com/testdouble/standard) for formatting Ruby code. Please make sure to run `rake` before submitting pull requests.
+
+
+## License
+
+Courrier is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+Minitest::TestTask.create
+
+task default: %i[test standard]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "courrier"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/release

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+VERSION=$1
+
+if [ -z "$VERSION" ]; then
+  echo "Error: The version number is required."
+  echo "Usage: $0 <version-number>"
+  exit 1
+fi
+
+printf "module Courrier\n  VERSION = \"$VERSION\"\nend\n" > ./lib/courrier/version.rb
+bundle
+git add Gemfile.lock lib/courrier/version.rb
+git commit -m "Bump version for $VERSION"
+git push
+git tag v$VERSION
+git push --tags
+gem build courrier.gemspec
+gem push "courrier-$VERSION.gem"

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/courrier.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/courrier/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "courrier"
+  spec.version = Courrier::VERSION
+  spec.authors = ["Rails Designer"]
+  spec.email = ["devs@railsdesigner.com"]
+
+  spec.summary = "Modern, API-powered email delivery for Rails apps"
+  spec.description = "Modern, API-powered email delivery for Ruby apps with support for Postmark, SendGrid, Mailgun and more."
+  spec.homepage = "https://railsdesigner.com/courrier/"
+  spec.license = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Rails-Designer/courrier/"
+
+  spec.files = Dir["{bin,app,config,db,lib,public}/**/*", "Rakefile", "README.md", "courrier.gemspec", "Gemfile", "Gemfile.lock"]
+
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.add_dependency "launchy", ">= 3.1", "< 4"
+  spec.add_dependency "nokogiri", ">= 1.18", "< 2"
+end

data/lib/courrier/configuration/preview.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Configuration
+    class Preview
+      attr_accessor :destination, :auto_open, :template_path
+
+      def initialize
+        @destination = default_destination
+        @auto_open = true
+        @template_path = File.expand_path("../../../courrier/email/providers/preview/default.html.erb", __FILE__)
+      end
+
+      private
+
+      def default_destination
+        return Rails.root.join("tmp", "courrier", "emails").to_s if defined?(Rails)
+
+        File.join(Dir.tmpdir, "courrier", "emails")
+      end
+    end
+  end
+end

data/lib/courrier/configuration/providers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Configuration
+    class Providers
+      def initialize
+        @providers = {}
+      end
+
+      def method_missing(name, *, **)
+        @providers[name.to_sym] ||= ProviderConfig.new
+      end
+
+      def respond_to_missing?(name, include_private = false) = true
+
+      def [](provider_name)
+        @providers[provider_name.to_sym] ||= ProviderConfig.new
+      end
+
+      def to_h = @providers.transform_values(&:to_h)
+    end
+
+    class ProviderConfig
+      def initialize
+        @options = {}
+      end
+
+      def method_missing(name, value = nil, **)
+        option_name = name.to_s.chomp("=").to_sym
+
+        return @options[option_name] = value if name.to_s.end_with?("=")
+
+        @options[name.to_sym]
+      end
+
+      def respond_to_missing?(name, include_private = false) = true
+
+      def to_h = @options
+    end
+  end
+end

data/lib/courrier/configuration.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "courrier/configuration/preview"
+require "courrier/configuration/providers"
+
+module Courrier
+  class << self
+    attr_writer :configuration
+
+    def configure
+      self.configuration ||= Configuration.new
+
+      yield(configuration) if block_given?
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+  end
+
+  class Configuration
+    attr_accessor :provider, :api_key, :logger, :email_path, :layouts, :default_url_options, :auto_generate_text,
+      :from, :reply_to, :cc, :bcc
+    attr_reader :providers, :preview
+
+    def initialize
+      @provider = "logger"
+      @api_key = nil
+      @logger = ::Logger.new($stdout)
+      @email_path = default_email_path
+
+      @layouts = nil
+      @default_url_options = {host: ""}
+      @auto_generate_text = false
+
+      @from = nil
+      @reply_to = nil
+      @cc = nil
+      @bcc = nil
+
+      @providers = Courrier::Configuration::Providers.new
+      @preview = Courrier::Configuration::Preview.new
+    end
+
+    private
+
+    def default_email_path
+      return Rails.root.join("app", "emails").to_s if defined?(Rails)
+
+      File.join("courrier", "emails")
+    end
+  end
+end

data/lib/courrier/email/address.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Email
+    module Address
+      class << self
+        def with_name(address, name)
+          raise Courrier::ArgumentError, "Both `address` and `name` are required" if address.nil? || name.nil?
+          raise Courrier::ArgumentError, "Both `address` and `name` must not be empty" if address.empty? || name.empty?
+
+          address = address.gsub(/[<>]/, "")
+          formatted_name = format_display_for(name)
+
+          "#{formatted_name} <#{address}>"
+        end
+
+        private
+
+        def format_display_for(name)
+          return quote_escaped(name) if special_characters_in?(name)
+
+          name
+        end
+
+        def quote_escaped(name) = %("#{name.gsub('"', '\\"')}")
+
+        def special_characters_in?(name)
+          name =~ /[(),.:;<>@\[\]"]/
+        end
+      end
+
+      def email_with_name(email, name) = Address.with_name(email, name)
+      alias_method :email_address_with_name, :email_with_name
+      module_function :email_with_name, :email_address_with_name
+    end
+  end
+end

data/lib/courrier/email/layouts.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Email
+    class Layouts
+      def initialize(email)
+        @email = email
+      end
+
+      def build
+        return [] if no_layouts?
+
+        [layouts]
+      end
+
+      private
+
+      FORMATS = %w[html text]
+
+      def no_layouts? = @email.class.layouts.nil?
+
+      def layouts
+        FORMATS.map(&:to_sym).to_h do |format|
+          template = @email.class.layouts[format]
+
+          next if template.nil?
+
+          [format, render(template)]
+        end
+      end
+
+      def render(template)
+        return @email.send(template) if template.is_a?(Symbol)
+        return template.call if template.is_a?(Class)
+
+        template
+      end
+    end
+  end
+end