gemstack-mail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f307a2cbc3114db71b11ebfd91308197c64b1ac2e62ff5de5c228eef8aa55afd
+  data.tar.gz: 1154fb801ecab736d9c38f47fc66c3f35038b7b16139c6ae40e2cc603a6e77bb
+SHA512:
+  metadata.gz: 377bce3b6a5d4d460e595304fe2d68aba4e4bd847c307fdd7082b7ef91473183baaea175b61185e422851d5f06b1cbb222f546bdcc27fa7a20bedfd30efe0a01
+  data.tar.gz: d2bf854eaacf75de80a3b1c32629b9277e33755e6097bac4757712024100748f3f08251162e4fd29db6e1abb1bb058a982c7740afcb4bc6bfd24bf3148ce8cc8

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,28 @@
+# gemstack-mail
+
+GemStack mail: mailers, templates, SMTP/log/test delivery, deliver_later via jobs.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Optional module — `gemstack add auth`, or add it to the Gemfile:
+
+```ruby
+gem "gemstack-mail", "~> 0.1"
+```
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/mail.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-mail`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/mail/delivery_job.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "gemstack/jobs"
+
+module GemStack
+  module Mail
+    # Delivers a mailer action in the background (Delivery#deliver_later).
+    # Retried like any job; SMTP errors are transient more often than not.
+    class DeliveryJob < GemStack::Job
+      def self.queue(name = nil) = name ? super : (@queue || Mail.config.queue)
+
+      def perform(mailer_name, action, args)
+        mailer = Object.const_get(mailer_name)
+        raise ArgumentError, "#{mailer_name} is not a GemStack::Mailer" unless mailer.is_a?(Class) && mailer < Mailer
+
+        Mailer::Delivery.new(mailer, action, args).deliver_now
+      end
+    end
+  end
+end

data/lib/gemstack/mail/testing.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "gemstack/mail"
+
+module GemStack
+  module Mail
+    # Test helpers (included into GemStack::TestCase by `gemstack add auth`):
+    #
+    #   assert_emails(1) { post_json "/api/auth/password/forgot", { email: user.email } }
+    #   assert_equal [user.email], last_email.to
+    module Testing
+      def before_setup
+        super
+        Mail.deliveries.clear
+      end
+
+      def deliveries = Mail.deliveries
+      def last_email = Mail.deliveries.last
+
+      def assert_emails(count, &block)
+        before = Mail.deliveries.size
+        adapter = defined?(GemStack::Jobs) && GemStack::Jobs.adapter
+        adapter = nil unless adapter.respond_to?(:perform_enqueued)
+        queued = adapter ? adapter.enqueued.map { |job| job["id"] } : []
+        block&.call
+        # deliver_later mail sent inside the block counts too.
+        adapter&.perform_enqueued(only: ["GemStack::Mail::DeliveryJob"], except_ids: queued)
+        assert_equal count, Mail.deliveries.size - before,
+                     "Expected #{count} email(s), got #{Mail.deliveries.size - before}"
+      end
+    end
+  end
+end

data/lib/gemstack/mail.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+require "mail"
+require "erubi"
+require "uri"
+require "gemstack/core"
+
+module GemStack
+  # Email (DECISIONS D-047).
+  #
+  #   class AccountMailer < GemStack::Mailer
+  #     default from: "Shop <hello@shop.test>"
+  #
+  #     def welcome(user_id)
+  #       @user = User.find(user_id)
+  #       mail to: @user.email, subject: "Welcome!" # templates/account_mailer/welcome.{text,html}.erb
+  #     end
+  #   end
+  #
+  #   AccountMailer.welcome(user.id).deliver_later   # through GemStack::Jobs (pass ids)
+  #   AccountMailer.welcome(user.id).deliver_now
+  module Mail
+    class Config < Settings
+      # :smtp (production), :log (development: logged and saved to tmp/mail),
+      # :test (captured in GemStack::Mail.deliveries), or an object with #deliver(message).
+      setting :delivery, default: lambda {
+        if GemStack.env.test? then :test
+        elsif GemStack.env.development? then :log
+        else :smtp
+        end
+      }
+      # smtp://user:password@smtp.example.com:587 (STARTTLS) or smtps://…:465
+      setting :smtp_url, default: -> { ENV.fetch("SMTP_URL", nil) }
+      setting :default_from, default: -> { ENV.fetch("MAIL_FROM", "#{GemStack.config.name} <no-reply@localhost>") }
+      setting :templates_path, default: "app/mailers/templates"
+      setting :preview_dir, default: "tmp/mail"
+      # Queue used by deliver_later.
+      setting :queue, default: "mailers"
+    end
+
+    class DeliveryError < Error; end
+
+    # Loaded on first use, also by a jobs worker resolving the queued class name.
+    autoload :DeliveryJob, "gemstack/mail/delivery_job"
+
+    @deliveries = []
+    @mutex = Mutex.new
+
+    class << self
+      def config = GemStack.config.mail
+
+      # Messages delivered with the :test method.
+      attr_reader :deliveries
+
+      def deliver(message)
+        method = config.delivery
+        case method
+        when :test, "test" then @mutex.synchronize { @deliveries << message }
+        when :log, "log" then deliver_to_log(message)
+        when :smtp, "smtp" then deliver_smtp(message)
+        else
+          unless method.respond_to?(:deliver)
+            raise ConfigurationError,
+                  "a mail delivery method must respond to #deliver"
+          end
+
+          method.deliver(message)
+        end
+        GemStack.logger.info("mail.delivered", to: Array(message.to).join(","), subject: message.subject,
+                                               via: method.is_a?(Symbol) ? method : method.class.name)
+        message
+      end
+
+      def smtp_settings(url = config.smtp_url)
+        if url.to_s.empty?
+          raise ConfigurationError,
+                "set SMTP_URL (e.g. smtp://user:pass@smtp.example.com:587) to send mail"
+        end
+
+        uri = URI.parse(url)
+        {
+          address: uri.host, port: uri.port || (uri.scheme == "smtps" ? 465 : 587),
+          user_name: uri.user && URI.decode_www_form_component(uri.user),
+          password: uri.password && URI.decode_www_form_component(uri.password),
+          authentication: uri.user ? :plain : nil, tls: uri.scheme == "smtps",
+          enable_starttls_auto: uri.scheme != "smtps", open_timeout: 5, read_timeout: 10
+        }.compact
+      end
+
+      private
+
+      def deliver_smtp(message)
+        message.delivery_method(:smtp, smtp_settings)
+        message.deliver
+      rescue Net::SMTPError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError => e
+        raise DeliveryError, "SMTP delivery failed: #{e.class}: #{e.message}"
+      end
+
+      # Development: a log line plus a copy on disk (.eml, and .html to open in a browser).
+      def deliver_to_log(message)
+        dir = File.expand_path(config.preview_dir, GemStack.config.root)
+        FileUtils.mkdir_p(dir)
+        slug = message.subject.to_s.downcase.gsub(/[^a-z0-9]+/, "-").delete_prefix("-")[0, 40]
+        base = File.join(dir, "#{Time.now.strftime("%Y%m%d-%H%M%S-%L")}-#{slug}")
+        File.write("#{base}.eml", message.to_s)
+        html = message.html_part&.decoded
+        File.write("#{base}.html", html) if html
+        GemStack.logger.info("mail saved", to: Array(message.to).join(","), subject: message.subject,
+                                           file: "#{base}#{".html" if html}")
+      end
+    end
+  end
+
+  # Base class for mailers. Public instance methods are mail "actions";
+  # calling one on the class returns a Delivery. An action that returns
+  # without calling `mail` sends nothing (e.g. the user was deleted since).
+  class Mailer
+    # Rendered as the value of @variables set in the action.
+    class TemplateContext
+      def initialize(mailer)
+        mailer.instance_variables.each { |ivar| instance_variable_set(ivar, mailer.instance_variable_get(ivar)) }
+      end
+
+      def render(source, escape:) = instance_eval(Erubi::Engine.new(source, escape: escape).src)
+    end
+
+    # A message waiting to be delivered.
+    class Delivery
+      attr_reader :mailer_class, :action, :args
+
+      def initialize(mailer_class, action, args)
+        @mailer_class = mailer_class
+        @action = action
+        @args = args
+      end
+
+      def message
+        return @message if defined?(@message)
+
+        @message = mailer_class.new.build(action, args)
+      end
+
+      # nil when the action decided not to send (it returned without calling mail).
+      def deliver_now
+        msg = message
+        msg && Mail.deliver(msg)
+      end
+
+      # Delivers from a background job (arguments must be JSON values — pass ids).
+      def deliver_later(wait: nil)
+        require "gemstack/jobs"
+        job = wait ? Mail::DeliveryJob.set(wait: wait) : Mail::DeliveryJob
+        job.perform_later(mailer_class.name, action.to_s, args)
+      rescue LoadError
+        raise ConfigurationError, "deliver_later needs gemstack-jobs; add it to the Gemfile or use deliver_now"
+      end
+    end
+
+    class << self
+      def default(**headers) = defaults.merge!(headers.transform_keys(&:to_sym))
+      def defaults = @defaults ||= superclass.respond_to?(:defaults) ? superclass.defaults.dup : {}
+
+      def actions
+        (public_instance_methods(true) - Mailer.public_instance_methods(true)).map(&:to_s)
+      end
+
+      def respond_to_missing?(name, include_private = false) = actions.include?(name.to_s) || super
+
+      def method_missing(name, *args)
+        return super unless actions.include?(name.to_s)
+
+        Delivery.new(self, name.to_s, args)
+      end
+    end
+
+    def build(action, args)
+      @action = action
+      public_send(action, *args)
+      GemStack.logger.debug("mail skipped", mailer: self.class.name, action: action) unless @message
+      @message
+    end
+
+    # Builds the message. Bodies come from text:/html: or, when omitted, from
+    # templates: <templates_path>/<mailer>/<action>.text.erb and .html.erb
+    # (HTML templates escape <%= %> output; use <%== %> for trusted markup).
+    def mail(to:, subject:, text: nil, html: nil, from: nil, cc: nil, bcc: nil, reply_to: nil, template: @action)
+      headers = self.class.defaults
+      text ||= render_template(template, "text", escape: false)
+      html ||= render_template(template, "html", escape: true)
+      raise Error, "#{self.class.name}##{@action}: no body (give text:/html: or add a template)" unless text || html
+
+      @message = build_message(to: to, subject: subject, text: text, html: html,
+                               from: from || headers[:from] || Mail.config.default_from, cc: cc, bcc: bcc,
+                               reply_to: reply_to || headers[:reply_to])
+    end
+
+    private
+
+    def render_template(name, format, escape:)
+      path = File.join(GemStack.config.root, Mail.config.templates_path, Inflector.underscore(self.class.name),
+                       "#{name}.#{format}.erb")
+      return nil unless File.file?(path)
+
+      TemplateContext.new(self).render(File.read(path), escape: escape)
+    end
+
+    def build_message(to:, subject:, text:, html:, from:, cc:, bcc:, reply_to:)
+      message = ::Mail.new
+      message.from = from
+      message.to = to
+      message.cc = cc if cc
+      message.bcc = bcc if bcc
+      message.reply_to = reply_to if reply_to
+      message.subject = subject
+      if text
+        message.text_part = ::Mail::Part.new do
+          body text
+          content_type "text/plain; charset=UTF-8"
+        end
+      end
+      if html
+        message.html_part = ::Mail::Part.new do
+          body html
+          content_type "text/html; charset=UTF-8"
+        end
+      end
+      message
+    end
+  end
+end
+
+GemStack::Config.namespace(:mail, GemStack::Mail::Config)

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: gemstack-mail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shoaib Malik
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: erubi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: gemstack-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+email:
+- gemstack26@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/gemstack/mail.rb
+- lib/gemstack/mail/delivery_job.rb
+- lib/gemstack/mail/testing.rb
+homepage: https://github.com/gemstack-rb/gemstack
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/gemstack-rb/gemstack/tree/main/gems/gemstack-mail
+  changelog_uri: https://github.com/gemstack-rb/gemstack/blob/main/gems/gemstack-mail/CHANGELOG.md
+  bug_tracker_uri: https://github.com/gemstack-rb/gemstack/issues
+  documentation_uri: https://github.com/gemstack-rb/gemstack/tree/main/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'GemStack mail: mailers, templates, SMTP/log/test delivery, deliver_later
+  via jobs'
+test_files: []