lockally-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ea1171ccc4dd2969fd75c5c18484b89cc350994b44293e2ac3d425ff1c0cdf7
+  data.tar.gz: 5195841fe6c9cac0988904b7bb9965ad3a239ffe5fd071a3a75a026223c6466d
+SHA512:
+  metadata.gz: f8629d1a8a23b2f74a9ea37a4acc605670e13446c59c9c988fd9fadb6819ab7cd88ec0a15a939838dee1f327d72afe5dc0100378dc38c573395c2bfe2f922e8b
+  data.tar.gz: fc81ead5b95f2693d2fd047e17306973e5507e01c52ec32bc46bb3957c4ffc84d60bef14541861b86eb66a27085647a03599bb464852a9b3afec67df2d6d470c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lockally
+
+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,55 @@
+# lockally-rails
+
+Official [Lockally](https://lockally.com) ActionMailer adapter for Rails. Point Rails
+mail at Lockally and every `deliver`/`deliver_later` — from mailers, Devise, Action
+Mailbox bounces, anything — is delivered by Lockally with no other changes.
+
+## Install
+
+```ruby
+# Gemfile
+gem "lockally-rails"
+```
+
+```bash
+bundle install
+```
+
+## Configure
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :lockally
+config.action_mailer.lockally_settings = {
+  api_key: ENV["LOCKALLY_API_KEY"],          # lk_test_… runs in sandbox
+  # base_url: "https://api.lockally.com",     # optional override
+}
+```
+
+The railtie registers the `:lockally` delivery method automatically when Rails boots.
+
+## Send
+
+Nothing special — use ActionMailer as usual:
+
+```ruby
+class UserMailer < ApplicationMailer
+  def welcome(user)
+    mail(from: "alerts@yourdomain.com", to: user.email, subject: "Welcome",
+         reply_to: "support@yourdomain.com")
+  end
+end
+
+UserMailer.welcome(user).deliver_later
+```
+
+### Mapping notes
+
+- **Reply-To** is sent as a header (Lockally has no `reply_to` field).
+- **Attachments** are base64-encoded as `{ filename, content_type, content_base64 }`.
+- Multipart mail maps its text and HTML parts to `text` / `html`.
+- One `Idempotency-Key` is generated per send (24 h dedupe window).
+
+## License
+
+MIT © Lockally

data/lib/lockally/rails/delivery_method.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "base64"
+require "securerandom"
+require "lockally"
+
+module Lockally
+  module Rails
+    # ActionMailer delivery method that sends through the Lockally API (POST /v1/send).
+    #
+    # Registered as `:lockally` by the railtie, so:
+    #
+    #   config.action_mailer.delivery_method = :lockally
+    #   config.action_mailer.lockally_settings = { api_key: ENV["LOCKALLY_API_KEY"] }
+    #
+    # routes every ActionMailer `deliver`/`deliver_later` through Lockally.
+    class DeliveryMethod
+      attr_reader :settings
+
+      def initialize(settings = {})
+        @settings = settings || {}
+        @send_api = settings[:send_api] # injectable for tests
+      end
+
+      # ActionMailer calls this with a Mail::Message.
+      def deliver!(mail)
+        send_api.v1_send_post(idempotency_key, build_request(mail))
+      end
+
+      # Map a Mail::Message onto the Lockally send request. Public for unit testing.
+      def build_request(mail)
+        ::Lockally::V1SendPostRequest.new(build_payload(mail))
+      end
+
+      def build_payload(mail)
+        payload = {
+          from: Array(mail.from).first,
+          to: Array(mail.to),
+        }
+        payload[:cc] = Array(mail.cc) if mail.cc
+        payload[:bcc] = Array(mail.bcc) if mail.bcc
+        payload[:subject] = mail.subject if mail.subject
+
+        text, html = bodies(mail)
+        payload[:text] = text if text
+        payload[:html] = html if html
+
+        headers = custom_headers(mail)
+        payload[:headers] = headers unless headers.empty?
+
+        attachments = mail.attachments.map do |part|
+          ::Lockally::V1SendPostRequestAttachmentsInner.new(
+            filename: part.filename || "attachment",
+            content_type: part.mime_type || "application/octet-stream",
+            content_base64: Base64.strict_encode64(part.body.decoded),
+          )
+        end
+        payload[:attachments] = attachments unless attachments.empty?
+
+        payload
+      end
+
+      private
+
+      # Returns [text, html]. Handles multipart and single-part messages.
+      def bodies(mail)
+        if mail.multipart?
+          text = mail.text_part&.body&.decoded
+          html = mail.html_part&.body&.decoded
+          [text, html]
+        elsif mail.mime_type == "text/html"
+          [nil, mail.body.decoded]
+        else
+          [mail.body.decoded, nil]
+        end
+      end
+
+      # Lockally has no reply_to field, so Reply-To is carried in headers; standard
+      # MIME headers the Mail gem manages are skipped.
+      def custom_headers(mail)
+        managed = %w[from to cc bcc subject reply-to sender date message-id
+                     content-type content-transfer-encoding mime-version]
+        out = {}
+        out["Reply-To"] = Array(mail.reply_to).join(", ") if mail.reply_to
+        mail.header.fields.each do |field|
+          next if managed.include?(field.name.downcase)
+
+          out[field.name] = field.value.to_s
+        end
+        out
+      end
+
+      def send_api
+        @send_api ||= begin
+          config = ::Lockally::Configuration.new
+          config.access_token = settings[:api_key]
+          if settings[:base_url]
+            require "uri"
+            uri = URI.parse(settings[:base_url])
+            config.scheme = uri.scheme if uri.scheme
+            config.host = [uri.host, uri.port].compact.join(":")
+          end
+          ::Lockally::SendApi.new(::Lockally::ApiClient.new(config))
+        end
+      end
+
+      def idempotency_key
+        "lk-#{SecureRandom.hex(16)}"
+      end
+    end
+  end
+end

data/lib/lockally/rails/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "lockally/rails/delivery_method"
+
+module Lockally
+  module Rails
+    # Registers the `:lockally` ActionMailer delivery method when Rails boots.
+    class Railtie < ::Rails::Railtie
+      initializer "lockally.add_delivery_method" do
+        ActiveSupport.on_load(:action_mailer) do
+          add_delivery_method(:lockally, Lockally::Rails::DeliveryMethod)
+        end
+      end
+    end
+  end
+end

data/lib/lockally/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lockally
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/lockally/rails.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "lockally"
+require "lockally/rails/version"
+require "lockally/rails/delivery_method"
+# Load the railtie only when running inside Rails (so the delivery method can also
+# be used standalone, e.g. in tests or non-Rails apps).
+require "lockally/rails/railtie" if defined?(::Rails::Railtie)
+
+module Lockally
+  # ActionMailer adapter for Lockally. See Lockally::Rails::DeliveryMethod.
+  module Rails
+  end
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: lockally-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Lockally
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lockally
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Send transactional email from Rails through Lockally by setting config.action_mailer.delivery_method
+  = :lockally.
+email:
+- support@lockally.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/lockally/rails.rb
+- lib/lockally/rails/delivery_method.rb
+- lib/lockally/rails/railtie.rb
+- lib/lockally/rails/version.rb
+homepage: https://github.com/lockallyinc/lockally-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://lockally.com
+  source_code_uri: https://github.com/lockallyinc/lockally-rails
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Lockally ActionMailer adapter for Rails
+test_files: []