courrier 0.5.0

data/lib/courrier/email/request.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "courrier/email/result"
+
+module Courrier
+  class Email
+    class Request
+      def initialize(endpoint_url:, body:, provider:, headers: {}, content_type: "application/json")
+        @endpoint_url = endpoint_url
+        @body = body
+        @provider = provider
+        @headers = headers
+        @content_type = content_type
+      end
+
+      def post
+        uri = URI.parse(@endpoint_url)
+        request = Net::HTTP::Post.new(uri)
+
+        headers_for request
+        body_for request
+
+        options = {use_ssl: uri.scheme == "https"}
+
+        begin
+          response = Net::HTTP.start(uri.hostname, uri.port, options) { _1.request(request) }
+
+          Result.new(response: response)
+        rescue => error
+          Result.new(error: error)
+        end
+      end
+
+      private
+
+      def headers_for(request)
+        default_headers.merge(@headers).each do |key, value|
+          request[key] = value
+        end
+      end
+
+      def body_for(request)
+        if requires_multipart_form?
+          set_multipart_form(request)
+        else
+          set_json_body(request)
+        end
+      end
+
+      def default_headers
+        {
+          "Content-Type" => @content_type,
+          "Accept" => "application/json"
+        }
+      end
+
+      def requires_multipart_form?
+        ["Mailgun"].include?(@provider)
+      end
+
+      def set_multipart_form(request)
+        request.set_form(@body, "multipart/form-data")
+      end
+
+      def set_json_body(request)
+        request.content_type = "application/json"
+        request.body = JSON.dump(@body)
+      end
+    end
+  end
+end

data/lib/courrier/email/result.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Courrier
+  class Email
+    class Result
+      attr_reader :success, :response, :data, :error
+
+      def initialize(response: nil, error: nil)
+        @response = response
+        @error = error
+        @data = parse_body(@response&.body)
+        @success = successful?
+      end
+
+      def success? = @success
+
+      private
+
+      def parse_body(body)
+        return {} if @response.nil?
+
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          {}
+        end
+      end
+
+      def successful?
+        return false if response_failed?
+        return @data["success"] if @data.key?("success")
+
+        (200..299).cover?(status_code)
+      end
+
+      def response_failed? = @error || @response.nil?
+
+      def status_code = @response.code.to_i
+    end
+  end
+end

data/lib/courrier/email/transformer.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Courrier
+  class Email
+    class Transformer
+      def initialize(content)
+        @content = content
+      end
+
+      def to_text
+        Nokogiri::HTML(@content)
+          .then { remove_unwanted_elements(_1) }
+          .then { process_links(_1) }
+          .then { preserve_line_breaks(_1) }
+          .then { clean_up(_1) }
+      end
+
+      private
+
+      BLOCK_ELEMENTS = %w[p div h1 h2 h3 h4 h5 h6 pre blockquote li]
+
+      def remove_unwanted_elements(html) = html.tap { _1.css("script, style").remove }
+
+      def process_links(html)
+        html.tap do |document|
+          document.css("a")
+            .select { valid?(_1) }
+            .reject { _1.text.strip.empty? || _1.text.strip == _1["href"] }
+            .each { _1.content = "#{_1.text.strip} (#{_1["href"]})" }
+        end
+      end
+
+      def preserve_line_breaks(html)
+        html.tap do |document|
+          document.css(BLOCK_ELEMENTS.join(",")).each { _1.after("\n") }
+        end
+      end
+
+      def clean_up(html) = html.text.strip.gsub(/ *\n */m, "\n").squeeze(" \n")
+
+      def valid?(link) = link["href"] && !link["href"].start_with?("#")
+    end
+  end
+end

data/lib/courrier/email.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "courrier/email/address"
+require "courrier/email/layouts"
+require "courrier/email/options"
+require "courrier/email/provider"
+
+module Courrier
+  class Email
+    attr_accessor :provider, :api_key, :default_url_options, :options
+
+    class << self
+      %w[provider api_key from reply_to cc bcc layouts default_url_options].each do |attribute|
+        define_method(attribute) do
+          instance_variable_get("@#{attribute}") ||
+            (superclass.respond_to?(attribute) ? superclass.send(attribute) : nil) ||
+            Courrier.configuration&.send(attribute)
+        end
+
+        define_method("#{attribute}=") do |value|
+          instance_variable_set("@#{attribute}", value)
+        end
+      end
+
+      def deliver(options = {})
+        new(options).deliver_now
+      end
+      alias_method :deliver_now, :deliver
+
+      def configure(**options)
+        options.each { |key, value| send("#{key}=", value) if respond_to?("#{key}=") }
+      end
+      alias_method :set, :configure
+
+      def layout(options = {})
+        self.layouts = options
+      end
+
+      def inherited(subclass)
+        super
+
+        # If you read this and know how to move this Rails-specific logic somewhere
+        # else, e.g. `lib/courrier/railtie.rb`, open a PR ❤️
+        if defined?(Rails) && Rails.application
+          subclass.include Rails.application.routes.url_helpers
+        end
+      end
+    end
+
+    def initialize(options = {})
+      @provider = options[:provider] || ENV["COURRIER_PROVIDER"] || self.class.provider || Courrier.configuration&.provider
+      @api_key = options[:api_key] || ENV["COURRIER_PROVIDER"] || self.class.api_key || Courrier.configuration&.api_key
+
+      @default_url_options = self.class.default_url_options.merge(options[:default_url_options] || {})
+      @context_options = options.except(:provider, :api_key, :from, :to, :reply_to, :cc, :bcc, :subject, :text, :html)
+      @options = Email::Options.new(
+        options.merge(
+          from: options[:from] || self.class.from || Courrier.configuration&.from,
+          reply_to: options[:reply_to] || self.class.reply_to || Courrier.configuration&.reply_to,
+          cc: options[:cc] || self.class.cc || Courrier.configuration&.cc,
+          bcc: options[:bcc] || self.class.bcc || Courrier.configuration&.bcc,
+          subject: subject,
+          text: text,
+          html: html,
+          auto_generate_text: Courrier.configuration&.auto_generate_text,
+          layouts: Courrier::Email::Layouts.new(self).build
+        )
+      )
+    end
+
+    def deliver
+      if delivery_disabled?
+        Courrier.configuration&.logger&.info "[Courrier] Email delivery skipped: delivery is disabled via environment variable"
+
+        return nil
+      end
+
+      Provider.new(
+        provider: @provider,
+        api_key: @api_key,
+        options: @options,
+        provider_options: Courrier.configuration&.providers&.[](@provider.to_s.downcase.to_sym)&.to_h
+      ).deliver
+    end
+    alias_method :deliver_now, :deliver
+
+    private
+
+    def delivery_disabled?
+      ENV["COURRIER_EMAIL_DISABLED"] == "true" || ENV["COURRIER_EMAIL_ENABLED"] == "false"
+    end
+
+    def method_missing(name, *) = @context_options[name]
+
+    def respond_to_missing?(name, include_private = false) = true
+  end
+end

data/lib/courrier/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Courrier
+  class Error < StandardError; end
+
+  class ArgumentError < ::ArgumentError; end
+
+  class NotImplementedError < ::NotImplementedError; end
+
+  class ConfigurationError < Error; end
+end

data/lib/courrier/railtie.rb

@@ -0,0 +1,23 @@
+module Courrier
+  class Railtie < Rails::Railtie
+    config.after_initialize do
+      Courrier::Email.default_url_options = Courrier.configuration.default_url_options
+    end
+
+    ActiveSupport.on_load(:action_view) do
+      include Courrier::Email::Address
+    end
+
+    ActiveSupport.on_load(:action_controller) do
+      include Courrier::Email::Address
+    end
+
+    ActiveSupport.on_load(:active_job) do
+      include Courrier::Email::Address
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/courrier.rake", __FILE__)
+    end
+  end
+end

data/lib/courrier/tasks/courrier.rake

@@ -0,0 +1,13 @@
+namespace :tmp do
+  task :courrier do
+    rm_rf Dir["#{Courrier.configuration.preview.destination}/[^.]*"], verbose: false
+  end
+
+  task clear: :courrier
+end
+
+namespace :courrier do
+  desc "Clear preview email files from `#{Courrier.configuration.preview.destination}`"
+
+  task clear: "tmp:courrier"
+end

data/lib/courrier/version.rb

@@ -0,0 +1,3 @@
+module Courrier
+  VERSION = "0.5.0"
+end

data/lib/courrier.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "courrier/version"
+require "courrier/errors"
+require "courrier/configuration"
+require "courrier/email"
+require "courrier/railtie" if defined?(Rails)
+
+module Courrier
+end

data/lib/generators/courrier/email_generator.rb

@@ -0,0 +1,19 @@
+module Courrier
+  class EmailGenerator < Rails::Generators::NamedBase
+    desc "Create a new Courrier Email class"
+
+    source_root File.expand_path("templates", __dir__)
+
+    check_class_collision suffix: "Email"
+
+    class_option :skip_suffix, type: :boolean, default: false
+
+    def copy_mailer_file
+      template "email.rb", File.join(Courrier.configuration.email_path, class_path, "#{file_name}#{options[:skip_suffix] ? "" : "_email"}.rb")
+    end
+
+    private
+
+    def parent_class = defined?(ApplicationEmail) ? ApplicationEmail : Courrier::Email
+  end
+end

data/lib/generators/courrier/install_generator.rb

@@ -0,0 +1,11 @@
+module Courrier
+  class InstallGenerator < Rails::Generators::Base
+    desc "Creates the initializer for Courrier"
+
+    source_root File.expand_path("templates", __dir__)
+
+    def copy_initializer_file
+      template "initializer.rb", "config/initializers/courrier.rb"
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+class <%= class_name %><%= options[:skip_suffix] ? "" : "Email" %> < <%= parent_class %>
+  def subject = ""
+
+  # Create HTML and text emails using:
+  # https://railsdesigner.com/minimal-email-editor/
+  def text
+    <<~TEXT
+    TEXT
+  end
+
+  def html
+    <<~HTML
+    HTML
+  end
+end

data/lib/generators/courrier/templates/initializer.rb.tt

@@ -0,0 +1,38 @@
+Courrier.configure do |config|
+  include Courrier::Email::Address
+
+  # Choose your email delivery provider
+  # Default: `logger`
+  # config.provider = ""
+
+  # Add your email provider's API key
+  # config.api_key = ""
+
+  # Configure provider-specific settings
+  # config.providers.loops.transactional_id = ""
+  # config.providers.mailgun.domain = ""
+
+
+  # Set default sender details
+  config.from = email_with_name("support@example.com", "Example Support") # => `Example Support <support@example.com>`
+  # config.reply_to = ""
+  # config.cc = ""
+  # config.bcc = ""
+
+
+  # Set host for Rails URL helpers, e.g. `{host: "https://railsdesigner.com/"}`
+  # config.default_url_options = {}
+
+  # Generate text version from HTML content
+  # Default: `false`
+  # config.auto_generate_text = false
+
+  # Location for generated Courrier Emails
+  # Default: `app/emails`
+  # config.email_path = ""
+
+
+  # Select logger for the `logger` provider
+  # Default: `::Logger.new($stdout)` - Ruby's built-in Logger
+  # config.logger = ""
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: courrier
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Rails Designer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-05-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: launchy
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.18'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: Modern, API-powered email delivery for Ruby apps with support for Postmark,
+  SendGrid, Mailgun and more.
+email:
+- devs@railsdesigner.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- bin/console
+- bin/release
+- bin/setup
+- courrier.gemspec
+- lib/courrier.rb
+- lib/courrier/configuration.rb
+- lib/courrier/configuration/preview.rb
+- lib/courrier/configuration/providers.rb
+- lib/courrier/email.rb
+- lib/courrier/email/address.rb
+- lib/courrier/email/layouts.rb
+- lib/courrier/email/options.rb
+- lib/courrier/email/provider.rb
+- lib/courrier/email/providers/base.rb
+- lib/courrier/email/providers/logger.rb
+- lib/courrier/email/providers/loops.rb
+- lib/courrier/email/providers/mailgun.rb
+- lib/courrier/email/providers/mailjet.rb
+- lib/courrier/email/providers/mailpace.rb
+- lib/courrier/email/providers/postmark.rb
+- lib/courrier/email/providers/preview.rb
+- lib/courrier/email/providers/preview/default.html.erb
+- lib/courrier/email/providers/sendgrid.rb
+- lib/courrier/email/providers/sparkpost.rb
+- lib/courrier/email/request.rb
+- lib/courrier/email/result.rb
+- lib/courrier/email/transformer.rb
+- lib/courrier/errors.rb
+- lib/courrier/railtie.rb
+- lib/courrier/tasks/courrier.rake
+- lib/courrier/version.rb
+- lib/generators/courrier/email_generator.rb
+- lib/generators/courrier/install_generator.rb
+- lib/generators/courrier/templates/email.rb.tt
+- lib/generators/courrier/templates/initializer.rb.tt
+homepage: https://railsdesigner.com/courrier/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railsdesigner.com/courrier/
+  source_code_uri: https://github.com/Rails-Designer/courrier/
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Modern, API-powered email delivery for Rails apps
+test_files: []