postpeek 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 22be47bd1a344e954412e45df776751e211891d001d4c136743d3b83f46fb767
+  data.tar.gz: 5eb48d5c14bd41fbebcdf835d3c5471604ec5b74e04c2842656a809580105f24
+SHA512:
+  metadata.gz: b039b3e4204cef36f83e7d91128f40ad3e5eb78b27a0f0fb4fa751ec6ed18dd7d6ce06731bb70360e4c9234a14c0ab79110e8295134eefdb4d7f4dd0a5b1a997
+  data.tar.gz: ed09f1c6ce00ea05bf7b94e9489796f1f6e17e13c91fbbdd7b253bd64f586653564356c1c62c04c09038630893c491d6febf4d0c928c7e6e5d482c1d33eaf8da

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-10
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"postpeek" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mmarusyk1@gmail.com"](mailto:"mmarusyk1@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mykhailo Marusyk
+
+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,43 @@
+# Postpeek
+
+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/postpeek`. To experiment with that code, run `bin/console` for an interactive prompt.
+
+## 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
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/postpeek. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/postpeek/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Postpeek project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/postpeek/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/postpeek/configuration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Postpeek
+  class Configuration
+    DEFAULTS = {
+      storage_path: nil,
+      storage_backend: :file_system,
+      unknown_encoding: :raise,
+      max_emails: 500,
+      auto_prune: true,
+      open_in_browser: false,
+      after_save: [],
+      metadata_builders: []
+    }.freeze
+
+    VALID_UNKNOWN_ENCODING_VALUES = %i[raise warn skip].freeze
+
+    attr_accessor :storage_path, :storage_backend, :unknown_encoding,
+                  :max_emails, :auto_prune, :open_in_browser,
+                  :after_save, :metadata_builders
+
+    def initialize
+      DEFAULTS.each { |key, value| public_send(:"#{key}=", deep_dup(value)) }
+    end
+
+    def resolved_storage_path
+      path = storage_path ||
+             (defined?(Rails) && Rails.respond_to?(:root) && Rails.root ? Rails.root.join("tmp", "postpeek") : nil) ||
+             Pathname.new(Dir.pwd).join("tmp", "postpeek")
+
+      Pathname.new(path)
+    end
+
+    def after_save_hook(callable = nil, &block)
+      after_save << (callable || block)
+    end
+
+    def metadata_builder(callable = nil, &block)
+      metadata_builders << (callable || block)
+    end
+
+    def validate!
+      unless VALID_UNKNOWN_ENCODING_VALUES.include?(unknown_encoding)
+        raise ArgumentError,
+              "unknown_encoding must be one of #{VALID_UNKNOWN_ENCODING_VALUES.inspect}, " \
+              "got #{unknown_encoding.inspect}"
+      end
+
+      if !max_emails.nil? && (!max_emails.is_a?(Integer) || max_emails <= 0)
+        raise ArgumentError, "max_emails must be a positive integer or nil, got #{max_emails.inspect}"
+      end
+
+      self
+    end
+
+    private
+
+    def deep_dup(value)
+      case value
+      when Array then value.dup
+      else value
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Decoders
+    class Base
+      # Returns the list of encoding strings this decoder handles.
+      # @return [Array<String>]
+      def self.handles
+        raise NotImplementedError, "#{self}.handles must be implemented by subclass"
+      end
+
+      # Decodes raw encoded content.
+      # @param content [String] encoded content
+      # @return [String] decoded content encoded as UTF-8
+      # @raise [DecodeError] if decoding fails
+      def decode(content)
+        raise NotImplementedError, "#{self.class}#decode must be implemented by subclass"
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/base64.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module Postpeek
+  module Decoders
+    class Base64 < Base
+      def self.handles
+        ["base64"].freeze
+      end
+
+      def decode(content)
+        decoded = ::Base64.decode64(content)
+
+        decoded.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+      rescue ArgumentError => e
+        raise DecodeError.new("base64", e)
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Decoders
+    class UnknownEncodingError < Postpeek::Error
+      attr_reader :encoding
+
+      def initialize(encoding)
+        @encoding = encoding
+
+        super("No decoder registered for encoding: #{encoding.inspect}")
+      end
+    end
+
+    class DecodeError < Postpeek::Error
+      attr_reader :encoding, :original_error
+
+      def initialize(encoding, original_error = nil)
+        @encoding = encoding
+        @original_error = original_error
+        message = "Failed to decode content with encoding #{encoding.inspect}"
+        message += ": #{original_error.message}" if original_error
+
+        super(message)
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/quoted_printable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Decoders
+    class QuotedPrintable < Base
+      def self.handles
+        ["quoted-printable"].freeze
+      end
+
+      def decode(content)
+        # unpack1("M") returns an ASCII-8BIT string; force UTF-8 interpretation
+        # before transcoding so multi-byte sequences are preserved.
+        decoded = content.unpack1("M").force_encoding("UTF-8")
+
+        if decoded.valid_encoding?
+          decoded
+        else
+          decoded.encode("UTF-8", "binary", invalid: :replace, undef: :replace,
+                                            replace: "")
+        end
+      rescue ArgumentError => e
+        raise DecodeError.new("quoted-printable", e)
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/registry.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Decoders
+    class Registry
+      class << self
+        # Registers a decoder class for all encodings it handles.
+        # @param decoder_class [Class<Base>]
+        def register(decoder_class)
+          decoder_class.handles.each do |encoding|
+            registry[encoding.downcase] = decoder_class
+          end
+        end
+
+        # Returns an instantiated decoder for the given encoding.
+        # Behaviour on unknown encoding is controlled by config.unknown_encoding:
+        #   :raise — raises UnknownEncodingError (default)
+        #   :warn  — logs a warning and returns nil
+        #   :skip  — silently returns nil
+        # @param encoding [String]
+        # @param config [Postpeek::Configuration]
+        # @return [Base, nil]
+        def find(encoding, config: Postpeek.configuration)
+          decoder_class = registry[encoding.to_s.downcase]
+
+          return decoder_class.new if decoder_class
+
+          handle_unknown_encoding(encoding, config)
+        end
+
+        # Returns a frozen copy of the current registry map.
+        # @return [Hash{String => Class}]
+        def registered
+          registry.dup.freeze
+        end
+
+        # Resets the registry to the built-in defaults. Intended for use in tests only.
+        def reset!
+          @registry = nil
+
+          seed_built_ins
+        end
+
+        private
+
+        def handle_unknown_encoding(encoding, config)
+          case config.unknown_encoding
+          when :raise then raise UnknownEncodingError, encoding
+          when :warn
+            warn "Postpeek: no decoder registered for encoding #{encoding.inspect}, skipping"
+          end
+          nil
+        end
+
+        def registry
+          @registry ||= {}.tap { seed_built_ins_into(_1) }
+        end
+
+        def seed_built_ins
+          seed_built_ins_into(registry)
+        end
+
+        def seed_built_ins_into(hash)
+          [QuotedPrintable, Base64, SevenBit].each do |klass|
+            klass.handles.each { |enc| hash[enc.downcase] = klass }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/postpeek/decoders/seven_bit.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Decoders
+    class SevenBit < Base
+      def self.handles
+        %w[7bit 8bit binary].freeze
+      end
+
+      def decode(content)
+        content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+      rescue ArgumentError => e
+        raise DecodeError.new("7bit", e)
+      end
+    end
+  end
+end

data/lib/postpeek/delivery_method.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Postpeek
+  class DeliveryMethod
+    # @param settings [Hash]  from ActionMailer::Base.postpeek_settings (unused in v0.1)
+    def initialize(settings = {})
+      @settings = settings
+    end
+
+    # Full pipeline:
+    # 1. Record start time
+    # 2. Decode parts (html_body, text_body, attachments)
+    # 3. Compute delivery_duration_ms
+    # 4. Build metadata via Metadata::Builder
+    # 5. Construct Message value object
+    # 6. Persist via storage backend
+    # 7. Run after_save hooks
+    def deliver!(mail)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      html_body, text_body, attachments = decode_parts(mail)
+      duration_ms = elapsed_ms(start_time)
+
+      metadata = Metadata::Builder.new(mail, config: config, delivery_duration_ms: duration_ms).build
+      message  = Message.new(mail: mail, metadata: metadata,
+                             html_body: html_body, text_body: text_body, attachments: attachments)
+
+      storage.save(message)
+      Hooks::Lifecycle.run_after_save(message, config: config)
+    end
+
+    private
+
+    def config
+      Postpeek.configuration
+    end
+
+    def elapsed_ms(start_time)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000).round
+    end
+
+    # Walks mail parts and decodes each using Decoders::Registry.
+    # @return [Array(String|nil, String|nil, Array<Hash>)]
+    #   [html_body, text_body, [{filename:, content_type:, data:}, ...]]
+    def decode_parts(mail)
+      parts = mail.multipart? ? mail.parts : [mail]
+      results = parts.map { |p| decode_one_part(p) }
+      html_body   = results.filter_map { |h, _, _| h }.first
+      text_body   = results.filter_map { |_, t, _| t }.first
+      attachments = results.flat_map { |_, _, a| a }
+      [html_body, text_body, attachments]
+    end
+
+    # Recursively decodes one part.
+    # @return [Array(String|nil, String|nil, Array<Hash>)]
+    def decode_one_part(part)
+      return recurse_multipart(part) if part.multipart?
+      return [nil, nil, [decode_attachment(part)]] if part.attachment?
+
+      decode_text_part(part)
+    end
+
+    def recurse_multipart(part)
+      results = part.parts.map { |sub| decode_one_part(sub) }
+      [
+        results.filter_map { |h, _, _| h }.first,
+        results.filter_map { |_, t, _| t }.first,
+        results.flat_map { |_, _, a| a }
+      ]
+    end
+
+    def decode_text_part(part)
+      if part.mime_type&.include?("text/html")
+        [decode_part(part), nil, []]
+      elsif part.mime_type&.include?("text/plain") || part.mime_type.nil?
+        [nil, decode_part(part), []]
+      else
+        [nil, nil, []]
+      end
+    end
+
+    # Decodes a single mail part. Returns nil if decoder returns nil (skip mode).
+    # Defaults to "7bit" when no Content-Transfer-Encoding header is present (RFC 2822).
+    def decode_part(part)
+      encoding = part.content_transfer_encoding.to_s
+      encoding = "7bit" if encoding.empty?
+      decoder  = Decoders::Registry.find(encoding, config: config)
+      return nil if decoder.nil?
+
+      decoder.decode(part.body.raw_source)
+    end
+
+    def decode_attachment(part)
+      {
+        filename: part.filename || "attachment",
+        content_type: part.mime_type,
+        data: part.body.decoded
+      }
+    end
+
+    # Returns the storage backend instance (memoized).
+    def storage
+      @storage ||= resolve_storage_backend.new(config)
+    end
+
+    def resolve_storage_backend
+      case config.storage_backend
+      when :file_system then Storage::FileSystem
+      when Class        then config.storage_backend
+      else raise ArgumentError, "Unknown storage backend: #{config.storage_backend.inspect}"
+      end
+    end
+  end
+end

data/lib/postpeek/hooks/lifecycle.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Hooks
+    module Lifecycle
+      # @param message [Postpeek::Message]
+      # @param config  [Postpeek::Configuration]
+      def self.run_after_save(message, config:)
+        config.after_save.each do |hook|
+          hook.call(message)
+        rescue StandardError => e
+          warn "Postpeek after_save hook raised: #{e.class}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/postpeek/id_generator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Postpeek
+  module IdGenerator
+    def self.generate
+      "#{Time.now.utc.strftime("%Y%m%dT%H%M%S")}_#{SecureRandom.hex(4)}"
+    end
+  end
+end

data/lib/postpeek/message.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Postpeek
+  class Message
+    # @param mail        [Mail::Message]
+    # @param metadata    [Hash]           from Builder#build
+    # @param html_body   [String, nil]    decoded HTML part
+    # @param text_body   [String, nil]    decoded plain-text part
+    # @param attachments [Array<Hash>]    [{filename:, content_type:, data: <binary>}, ...]
+    def initialize(mail:, metadata:, html_body: nil, text_body: nil, attachments: [])
+      @mail        = mail
+      @metadata    = metadata
+      @html_body   = html_body
+      @text_body   = text_body
+      @attachments = attachments
+    end
+
+    attr_reader :mail, :metadata, :html_body, :text_body, :attachments
+
+    def id
+      metadata[:id]
+    end
+
+    def subject
+      metadata[:subject]
+    end
+
+    def from
+      metadata[:from]
+    end
+
+    def to
+      metadata[:to]
+    end
+
+    def mailer_class
+      metadata[:mailer_class]
+    end
+
+    def mailer_action
+      metadata[:mailer_action]
+    end
+
+    def raw_source
+      mail.to_s
+    end
+  end
+end

data/lib/postpeek/metadata/action_mailer_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Metadata
+    module ActionMailerContext
+      THREAD_KEY_CLASS  = :postpeek_mailer_class
+      THREAD_KEY_ACTION = :postpeek_mailer_action
+
+      # Stores mailer context in Thread.current, yields, clears in ensure.
+      # @param mailer_class [String]
+      # @param action_name  [String]
+      def self.with(mailer_class, action_name)
+        Thread.current[THREAD_KEY_CLASS]  = mailer_class
+        Thread.current[THREAD_KEY_ACTION] = action_name
+        yield
+      ensure
+        Thread.current[THREAD_KEY_CLASS]  = nil
+        Thread.current[THREAD_KEY_ACTION] = nil
+      end
+
+      def self.current_mailer_class
+        Thread.current[THREAD_KEY_CLASS]
+      end
+
+      def self.current_action
+        Thread.current[THREAD_KEY_ACTION]
+      end
+
+      # Installs an around_action on ActionMailer::Base.
+      # Idempotent: guarded by @installed class-level flag.
+      def self.install!
+        return if @installed
+
+        @installed = true
+        ActionMailer::Base.around_action do |mailer, action|
+          ActionMailerContext.with(mailer.class.name, mailer.action_name) { action.call }
+        end
+      end
+    end
+  end
+end

data/lib/postpeek/metadata/builder.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Metadata
+    class Builder
+      # @param mail                  [Mail::Message]
+      # @param config                [Postpeek::Configuration]
+      # @param delivery_duration_ms  [Integer, nil]
+      def initialize(mail, config:, delivery_duration_ms: nil)
+        @mail                 = mail
+        @config               = config
+        @delivery_duration_ms = delivery_duration_ms
+      end
+
+      # Pipeline:
+      # 1. Extractor#to_h  — base fields
+      # 2. mailer_class + mailer_action from ActionMailerContext
+      #    (fallback: X-Postpeek-* headers when thread context is nil)
+      # 3. id = IdGenerator.generate
+      # 4. delivery_duration_ms (from arg)
+      # 5. tags: []
+      # 6. Call each config.metadata_builders callable(hash); merge result
+      # @return [Hash]
+      def build
+        hash = Extractor.new(mail).to_h
+        hash[:mailer_class]         = mailer_class_value
+        hash[:mailer_action]        = mailer_action_value
+        hash[:id]                   = IdGenerator.generate
+        hash[:delivery_duration_ms] = delivery_duration_ms
+        hash[:tags]                 = []
+        apply_metadata_builders(hash)
+      end
+
+      private
+
+      attr_reader :mail, :config, :delivery_duration_ms
+
+      def apply_metadata_builders(hash)
+        config.metadata_builders.each do |builder|
+          result = builder.call(hash)
+
+          raise ArgumentError, "metadata_builder must return a Hash, got #{result.class}" unless result.is_a?(Hash)
+
+          hash.merge!(result)
+        end
+        hash
+      end
+
+      def mailer_class_value
+        ActionMailerContext.current_mailer_class ||
+          header_string("X-Postpeek-Mailer-Class")
+      end
+
+      def mailer_action_value
+        ActionMailerContext.current_action ||
+          header_string("X-Postpeek-Mailer-Action")
+      end
+
+      def header_string(name)
+        val = mail[name]&.to_s
+
+        val&.empty? ? nil : val
+      end
+    end
+  end
+end

data/lib/postpeek/metadata/extractor.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Metadata
+    class Extractor
+      def initialize(mail)
+        @mail = mail
+      end
+
+      def subject
+        mail.subject
+      end
+
+      def from
+        normalise_addresses(mail.from)
+      end
+
+      def to
+        normalise_addresses(mail.to)
+      end
+
+      def cc
+        normalise_addresses(mail.cc)
+      end
+
+      def bcc
+        normalise_addresses(mail.bcc)
+      end
+
+      def reply_to
+        normalise_addresses(mail.reply_to).first
+      end
+
+      def sent_at
+        return nil unless mail.date
+
+        mail.date.to_time.utc.iso8601
+      end
+
+      def content_type
+        return nil unless mail.content_type
+
+        mail.mime_type
+      end
+
+      def parts
+        return [] unless mail.multipart?
+
+        mail.parts.map do |part|
+          {
+            content_type: part.mime_type,
+            encoding: part.content_transfer_encoding,
+            charset: part.charset
+          }
+        end
+      end
+
+      def encoding
+        mail.content_transfer_encoding&.to_s
+      end
+
+      def locale
+        header_val = mail["X-Mailer-Locale"]&.value
+
+        return header_val if header_val && !header_val.empty?
+
+        defined?(I18n) ? I18n.locale&.to_s : nil
+      end
+
+      def attachments
+        mail.attachments.map do |att|
+          {
+            filename: att.filename,
+            content_type: att.mime_type,
+            size: att.body.decoded.bytesize
+          }
+        end
+      end
+
+      def message_id
+        mail.message_id
+      end
+
+      def to_h
+        {
+          subject: subject, from: from, to: to, cc: cc, bcc: bcc,
+          reply_to: reply_to, sent_at: sent_at, content_type: content_type,
+          parts: parts, encoding: encoding, locale: locale,
+          attachments: attachments, message_id: message_id
+        }
+      end
+
+      private
+
+      attr_reader :mail
+
+      def normalise_addresses(field)
+        return [] if field.nil?
+
+        Array(field)
+      end
+    end
+  end
+end

data/lib/postpeek/metadata/interceptor.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Metadata
+    module Interceptor
+      def self.delivering_email(mail)
+        mail["X-Postpeek-Mailer-Class"]  = ActionMailerContext.current_mailer_class
+        mail["X-Postpeek-Mailer-Action"] = ActionMailerContext.current_action
+      end
+    end
+  end
+end

data/lib/postpeek/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Postpeek
+  class Railtie < Rails::Railtie
+    initializer "postpeek.configure_action_mailer" do
+      ActiveSupport.on_load(:action_mailer) do
+        ActionMailer::Base.add_delivery_method :postpeek, Postpeek::DeliveryMethod
+        Postpeek::Metadata::ActionMailerContext.install!
+        ActionMailer::Base.register_interceptor(Postpeek::Metadata::Interceptor)
+      end
+    end
+  end
+end

data/lib/postpeek/storage/base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Postpeek
+  module Storage
+    class Base
+      def initialize(config)
+        @config = config
+      end
+
+      def save(_message)
+        raise NotImplementedError, "#{self.class}#save not implemented"
+      end
+
+      def list
+        raise NotImplementedError, "#{self.class}#list not implemented"
+      end
+
+      def fetch(_id)
+        raise NotImplementedError, "#{self.class}#fetch not implemented"
+      end
+
+      def delete(_id)
+        raise NotImplementedError, "#{self.class}#delete not implemented"
+      end
+
+      def clear
+        raise NotImplementedError, "#{self.class}#clear not implemented"
+      end
+
+      def count
+        raise NotImplementedError, "#{self.class}#count not implemented"
+      end
+
+      private
+
+      attr_reader :config
+    end
+  end
+end

data/lib/postpeek/storage/file_system.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Postpeek
+  module Storage
+    class FileSystem < Base
+      ID_PATTERN = /\A\d{8}T\d{6}_[0-9a-f]{8}\z/
+
+      def save(message)
+        dir = email_dir(message.id)
+
+        FileUtils.mkdir_p(dir)
+        write_artifacts(dir, message)
+        prune_if_needed
+        message.id
+      end
+
+      def list
+        email_dirs.sort_by { |d| -File.mtime(d).to_i }.map { |d| File.basename(d) }
+      end
+
+      def fetch(id)
+        path = email_dir(id).join("metadata.json")
+
+        return nil unless path.exist?
+
+        JSON.parse(path.read, symbolize_names: true)
+      end
+
+      def delete(id)
+        FileUtils.rm_rf(email_dir(id))
+      end
+
+      def clear
+        email_dirs.each { |d| FileUtils.rm_rf(d) }
+      end
+
+      def count
+        email_dirs.length
+      end
+
+      private
+
+      def email_dir(id)
+        config.resolved_storage_path.join(id)
+      end
+
+      def email_dirs
+        root = config.resolved_storage_path
+        return [] unless root.exist?
+
+        root.children.select { |d| d.directory? && ID_PATTERN.match?(d.basename.to_s) }
+      end
+
+      def prune_if_needed
+        return if config.max_emails.nil? || !config.auto_prune
+
+        while count > config.max_emails
+          oldest = email_dirs.min_by { |d| File.mtime(d) }
+          FileUtils.rm_rf(oldest)
+        end
+      end
+
+      def write_artifacts(dir, message)
+        write_file(dir.join("metadata.json"), JSON.generate(message.metadata))
+        write_file(dir.join("message.eml"), message.raw_source)
+        write_body_parts(dir, message)
+        write_attachments(dir, message.attachments)
+      end
+
+      def write_body_parts(dir, message)
+        write_file(dir.join("rich.html"), message.html_body) if message.html_body
+        write_file(dir.join("plain.txt"), message.text_body) if message.text_body
+      end
+
+      def write_attachments(dir, attachments)
+        return if attachments.empty?
+
+        att_dir = dir.join("attachments")
+        FileUtils.mkdir_p(att_dir)
+        attachments.each do |att|
+          write_file(att_dir.join(sanitise_filename(att[:filename])), att[:data], binary: true)
+        end
+      end
+
+      def write_file(path, content, binary: false)
+        if binary
+          File.binwrite(path, content)
+        else
+          File.write(path, content)
+        end
+      end
+
+      def sanitise_filename(name)
+        name.to_s.gsub(%r{[/\\]}, "_").gsub(/[^\w.-]/, "_").then do |safe|
+          safe.empty? ? "attachment" : safe
+        end
+      end
+    end
+  end
+end

data/lib/postpeek/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Postpeek
+  VERSION = "0.1.0"
+end

data/lib/postpeek.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Postpeek
+  class Error < StandardError; end
+
+  class << self
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration object for block-based setup.
+    # @yieldparam config [Configuration]
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    # Resets configuration to defaults. Intended for use in tests only.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end
+
+require_relative "postpeek/version"
+require_relative "postpeek/id_generator"
+require_relative "postpeek/configuration"
+require_relative "postpeek/decoders/errors"
+require_relative "postpeek/decoders/base"
+require_relative "postpeek/decoders/quoted_printable"
+require_relative "postpeek/decoders/base64"
+require_relative "postpeek/decoders/seven_bit"
+require_relative "postpeek/decoders/registry"
+require_relative "postpeek/storage/base"
+require_relative "postpeek/storage/file_system"
+require_relative "postpeek/metadata/extractor"
+require_relative "postpeek/metadata/action_mailer_context"
+require_relative "postpeek/metadata/interceptor"
+require_relative "postpeek/metadata/builder"
+require_relative "postpeek/message"
+require_relative "postpeek/hooks/lifecycle"
+require_relative "postpeek/delivery_method"
+require_relative "postpeek/railtie" if defined?(Rails::Railtie)

data/mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.2"

data/sig/postpeek.rbs

@@ -0,0 +1,4 @@
+module Postpeek
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: postpeek
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mykhailo Marusyk
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !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'
+description: Postpeek intercepts ActionMailer deliveries in development, decodes content,
+  enriches metadata (mailer class, action, duration), and stores each email as a structured
+  directory on disk. A companion UI gem (postpeek_ui) reads the stored emails and
+  provides a filterable web interface.
+email:
+- mmarusyk1@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/postpeek.rb
+- lib/postpeek/configuration.rb
+- lib/postpeek/decoders/base.rb
+- lib/postpeek/decoders/base64.rb
+- lib/postpeek/decoders/errors.rb
+- lib/postpeek/decoders/quoted_printable.rb
+- lib/postpeek/decoders/registry.rb
+- lib/postpeek/decoders/seven_bit.rb
+- lib/postpeek/delivery_method.rb
+- lib/postpeek/hooks/lifecycle.rb
+- lib/postpeek/id_generator.rb
+- lib/postpeek/message.rb
+- lib/postpeek/metadata/action_mailer_context.rb
+- lib/postpeek/metadata/builder.rb
+- lib/postpeek/metadata/extractor.rb
+- lib/postpeek/metadata/interceptor.rb
+- lib/postpeek/railtie.rb
+- lib/postpeek/storage/base.rb
+- lib/postpeek/storage/file_system.rb
+- lib/postpeek/version.rb
+- mise.toml
+- sig/postpeek.rbs
+homepage: https://github.com/mmarusyk/postpeek
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mmarusyk/postpeek
+  source_code_uri: https://github.com/mmarusyk/postpeek
+  changelog_uri: https://github.com/mmarusyk/postpeek/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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.19
+signing_key:
+specification_version: 4
+summary: Rails mail interceptor that stores emails to disk for development inspection
+test_files: []