Add email attachment support for notification emails (#154)

Add three-level attachment configuration following the same pattern as
the existing CC feature (#107):
- Global: config.mailer_attachments (Hash, Array, Proc, or nil)
- Target: mailer_attachments method on target model
- Notifiable: overriding_notification_email_attachments method

Attachments support :content (binary data) or :path (local file) with
optional :mime_type. Works with both single and batch notification emails.

Author: simukappu

CHANGELOG.md

@@ -4,6 +4,8 @@
 Enhancements:
 
 * Add instance-level subscription support — subscribe to notifications from a specific notifiable instance, not just by notification key - [#202](https://github.com/simukappu/activity_notification/issues/202)
+* Add email attachment support for notification emails with three-level configuration (global, target, notifiable) - [#154](https://github.com/simukappu/activity_notification/issues/154)
+* Add documentation for `notification_email_allowed?` override - [#206](https://github.com/simukappu/activity_notification/pull/206)
 
 Breaking Changes:
 

ai-docs/issues/154/design.md

@@ -0,0 +1,156 @@
+# Design: Email Attachments Support (#154)
+
+## Overview
+
+Follows the same pattern as the CC feature (#107). Three-level configuration, no database changes, integrates into existing mailer helpers.
+
+## Attachment Specification Format
+
+```ruby
+{
+  filename: String,        # Required
+  content:  String/Binary, # Either :content or :path required
+  path:     String,        # Either :content or :path required
+  mime_type: String        # Optional, inferred from filename if omitted
+}
+```
+
+## Configuration Levels
+
+### 1. Global (`config.mailer_attachments`)
+
+```ruby
+# Single attachment
+config.mailer_attachments = { filename: 'terms.pdf', path: Rails.root.join('public', 'terms.pdf') }
+
+# Multiple attachments
+config.mailer_attachments = [
+  { filename: 'logo.png', path: Rails.root.join('app/assets/images/logo.png') },
+  { filename: 'terms.pdf', content: generate_pdf }
+]
+
+# Dynamic (Proc receives notification key)
+config.mailer_attachments = ->(key) {
+  key.include?('invoice') ? { filename: 'invoice.pdf', content: generate_invoice } : nil
+}
+```
+
+### 2. Target (`target.mailer_attachments`)
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_target email: :email
+
+  def mailer_attachments
+    admin? ? { filename: 'admin_guide.pdf', path: '/path/to/guide.pdf' } : nil
+  end
+end
+```
+
+### 3. Notifiable Override (`notifiable.overriding_notification_email_attachments`)
+
+```ruby
+class Invoice < ActiveRecord::Base
+  acts_as_notifiable :users, targets: -> { ... }
+
+  def overriding_notification_email_attachments(target, key)
+    { filename: "invoice_#{id}.pdf", content: generate_pdf }
+  end
+end
+```
+
+## Implementation
+
+### config.rb
+
+Add `mailer_attachments` attribute, initialize to `nil`.
+
+### mailers/helpers.rb
+
+#### New method: `mailer_attachments(target)`
+
+Same pattern as `mailer_cc(target)`:
+
+```ruby
+def mailer_attachments(target)
+  if target.respond_to?(:mailer_attachments)
+    target.mailer_attachments
+  elsif ActivityNotification.config.mailer_attachments.present?
+    if ActivityNotification.config.mailer_attachments.is_a?(Proc)
+      key = @notification ? @notification.key : nil
+      ActivityNotification.config.mailer_attachments.call(key)
+    else
+      ActivityNotification.config.mailer_attachments
+    end
+  else
+    nil
+  end
+end
+```
+
+#### New method: `resolve_attachments(key)`
+
+Resolve with notifiable override priority:
+
+```ruby
+def resolve_attachments(key)
+  if @notification&.notifiable&.respond_to?(:overriding_notification_email_attachments) &&
+     @notification.notifiable.overriding_notification_email_attachments(@target, key).present?
+    @notification.notifiable.overriding_notification_email_attachments(@target, key)
+  else
+    mailer_attachments(@target)
+  end
+end
+```
+
+#### New method: `process_attachments(mail_obj, specs)`
+
+```ruby
+def process_attachments(mail_obj, specs)
+  return if specs.blank?
+  Array(specs).each do |spec|
+    next if spec.blank?
+    validate_attachment_spec!(spec)
+    content = spec[:content] || File.read(spec[:path])
+    options = { content: content }
+    options[:mime_type] = spec[:mime_type] if spec[:mime_type]
+    mail_obj.attachments[spec[:filename]] = options
+  end
+end
+```
+
+#### Modified: `headers_for`
+
+Add attachment resolution, store in headers:
+
+```ruby
+attachment_specs = resolve_attachments(key)
+headers[:attachment_specs] = attachment_specs if attachment_specs.present?
+```
+
+#### Modified: `send_mail`
+
+Extract and process attachments:
+
+```ruby
+def send_mail(headers, fallback = nil)
+  attachment_specs = headers.delete(:attachment_specs)
+  begin
+    mail_obj = mail headers
+    process_attachments(mail_obj, attachment_specs)
+    mail_obj
+  rescue ActionView::MissingTemplate => e
+    if fallback.present?
+      mail_obj = mail headers.merge(template_name: fallback)
+      process_attachments(mail_obj, attachment_specs)
+      mail_obj
+    else
+      raise e
+    end
+  end
+end
+```
+
+### Generator Template
+
+Add commented configuration example to `activity_notification.rb` template.

ai-docs/issues/154/requirements.md

@@ -0,0 +1,64 @@
+# Requirements: Email Attachments Support (#154)
+
+## Overview
+
+Add support for email attachments to notification emails. Currently, users must override the mailer to add attachments. This feature provides a clean API following the same pattern as the existing CC feature (#107).
+
+## Requirements
+
+### R1: Global Attachment Configuration
+
+As a developer, I want to configure default attachments for all notification emails at the gem level.
+
+1. `config.mailer_attachments` in the initializer applies attachments to all notification emails
+2. Supports Hash (single), Array of Hash (multiple), Proc (dynamic), or nil (none)
+3. When Proc, called with notification key as parameter
+4. When nil or empty, no attachments added
+
+### R2: Target-Level Attachment Configuration
+
+As a developer, I want to define attachments at the target model level.
+
+1. When target defines `mailer_attachments` method, those attachments are used
+2. Returns Array of attachment specs, single Hash, or nil
+3. When nil, falls back to global configuration
+
+### R3: Notifiable-Level Attachment Override
+
+As a developer, I want to override attachments per notification type in the notifiable model.
+
+1. When notifiable defines `overriding_notification_email_attachments(target, key)`, used with highest priority
+2. Receives target and notification key as parameters
+3. When nil, falls back to target-level or global configuration
+
+### R4: Attachment Resolution Priority
+
+1. Priority order: notifiable override > target method > global configuration
+2. When higher-priority returns nil, fall back to next level
+3. When all return nil, send email without attachments
+
+### R5: Attachment Format
+
+1. Hash with `:filename` (required) and `:content` (binary data)
+2. Hash with `:filename` (required) and `:path` (local file path)
+3. Optional `:mime_type` key; inferred from filename if not provided
+4. Exactly one of `:content` or `:path` must be provided
+5. Multiple attachments as Array of Hashes
+
+### R6: Error Handling
+
+1. Missing `:filename` raises ArgumentError
+2. Missing both `:content` and `:path` raises ArgumentError
+3. Non-existent file path raises ArgumentError
+4. Non-Hash spec raises ArgumentError
+
+### R7: Backward Compatibility
+
+1. No attachments when `mailer_attachments` is not configured
+2. No database migrations required
+3. Existing mailer customizations continue to work
+
+### R8: Batch Notification Attachments
+
+1. Batch notification emails support attachments using the same configuration
+2. Same resolution priority applies

ai-docs/issues/154/tasks.md

@@ -0,0 +1,37 @@
+# Tasks: Email Attachments Support (#154)
+
+## Task 1: Configuration
+- [ ] Add `mailer_attachments` attr_accessor to Config class
+- [ ] Initialize to `nil` in Config#initialize
+- [ ] Add YARD documentation
+
+## Task 2: Attachment Validation
+- [ ] Add `validate_attachment_spec!(spec)` private method to Mailers::Helpers
+  - Validate spec is Hash
+  - Validate `:filename` present
+  - Validate exactly one of `:content` or `:path` present
+  - Validate file exists when `:path` provided
+  - Raise ArgumentError with descriptive messages
+
+## Task 3: Attachment Resolution
+- [ ] Add `mailer_attachments(target)` method (same pattern as `mailer_cc`)
+- [ ] Add `resolve_attachments(key)` method (notifiable override > target > global)
+- [ ] Add `process_attachments(mail_obj, specs)` method
+
+## Task 4: Mailer Integration
+- [ ] Modify `headers_for` to call `resolve_attachments` and store in headers
+- [ ] Modify `send_mail` to extract and process attachments
+
+## Task 5: Generator Template
+- [ ] Add `config.mailer_attachments` example to initializer template
+
+## Task 6: Tests
+- [ ] Config attribute tests (nil default, Hash/Array/Proc/nil assignment)
+- [ ] `validate_attachment_spec!` tests (valid specs, missing filename, missing content/path, both content and path, non-Hash, non-existent path)
+- [ ] `mailer_attachments(target)` resolution tests (target method, global Hash, global Proc, nil fallback)
+- [ ] `resolve_attachments` priority tests (notifiable override > target > global, nil fallback at each level)
+- [ ] `process_attachments` tests (single Hash, Array, nil, empty, with/without mime_type)
+- [ ] Integration: notification email with attachments (single, multiple, no attachments)
+- [ ] Integration: batch notification email with attachments
+- [ ] Backward compatibility: existing emails without attachments unchanged
+- [ ] Verify 100% coverage

docs/Functions.md

@@ -215,6 +215,76 @@ class Article < ActiveRecord::Base
 end
 ```
 
+#### Email attachments
+
+*activity_notification* supports email attachments at three levels with the same priority order as CC:
+
+1. **Notifiable model override** (highest priority) - using `overriding_notification_email_attachments` method
+2. **Target model method** - using `mailer_attachments` method
+3. **Global configuration** - using `config.mailer_attachments` setting
+
+Attachments are specified as a Hash (or Array of Hashes) with `:filename` and either `:content` (binary data) or `:path` (local file path). An optional `:mime_type` can be provided; otherwise it is inferred from the filename.
+
+##### Global attachment configuration
+
+Configure default attachments in *activity_notification.rb* initializer:
+
+```ruby
+# Single attachment from a local file
+config.mailer_attachments = {
+  filename: 'terms.pdf',
+  path: Rails.root.join('public', 'terms.pdf')
+}
+
+# Multiple attachments
+config.mailer_attachments = [
+  { filename: 'logo.png', path: Rails.root.join('app/assets/images/logo.png') },
+  { filename: 'terms.pdf', path: Rails.root.join('public', 'terms.pdf') }
+]
+
+# Dynamic attachments based on notification key
+config.mailer_attachments = ->(key) {
+  if key.include?('invoice')
+    { filename: 'invoice.pdf', content: generate_invoice_pdf }
+  else
+    nil # No attachments
+  end
+}
+```
+
+##### Target-level attachment configuration
+
+Define `mailer_attachments` method in your target model:
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_target
+
+  def mailer_attachments
+    if admin?
+      { filename: 'admin_guide.pdf', path: Rails.root.join('docs', 'admin_guide.pdf') }
+    else
+      nil # Falls back to global config
+    end
+  end
+end
+```
+
+##### Notifiable-level attachment override
+
+For per-notification attachments, implement `overriding_notification_email_attachments` in your notifiable model:
+
+```ruby
+class Invoice < ActiveRecord::Base
+  acts_as_notifiable :users,
+    targets: ->(invoice, key) { [invoice.user] }
+
+  def overriding_notification_email_attachments(target, key)
+    { filename: "invoice_#{number}.pdf", content: generate_pdf }
+  end
+end
+```
+
 #### i18n for email
 
 The subject of notification email can be put in your locale *.yml* files as **mail_subject** field:

lib/activity_notification/config.rb

@@ -91,6 +91,15 @@ class Config
     #   @return [String, Array<String>, Proc] CC email address(es) for notification email.
     attr_accessor :mailer_cc
 
+    # @overload mailer_attachments
+    #   Returns attachment specification(s) for notification emails
+    #   @return [Hash, Array<Hash>, Proc, nil] Attachment specification(s) for notification emails.
+    # @overload mailer_attachments=(value)
+    #   Sets attachment specification(s) for notification emails
+    #   @param [Hash, Array<Hash>, Proc, nil] mailer_attachments The new mailer_attachments
+    #   @return [Hash, Array<Hash>, Proc, nil] Attachment specification(s) for notification emails.
+    attr_accessor :mailer_attachments
+
     # @overload mailer
     #   Returns mailer class for email notification
     #   @return [String] Mailer class for email notification.
@@ -246,6 +255,7 @@ def initialize
       @subscribe_to_optional_targets_as_default = nil
       @mailer_sender                            = nil
       @mailer_cc                                = nil
+      @mailer_attachments                       = nil
       @mailer                                   = 'ActivityNotification::Mailer'
       @parent_mailer                            = 'ActionMailer::Base'
       @parent_job                               = 'ActiveJob::Base'