spree_emails 5.3.0.rc2 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb421dde6030d9545dfc232796bfd6d57471b11810a25fb978603b1b201b7a7c
-  data.tar.gz: 96ca08387036fe07dbf84ec3fd123af49e610b011df8d1d1336be6c311f1484b
+  metadata.gz: ad94798002ff9ee17fe903d6527b8d8951df1cc3e370daa70e13f6d4e54e8fbb
+  data.tar.gz: 141c28661d895e70ba76e1589a0dfd0107480b244f2fd96816b50316ace9cd13
 SHA512:
-  metadata.gz: 622794e6805b0baf261beaf2892e6b3c376ef622c552a951c0a718ce6ea4f07d28e2f74fef83c2c06a9d62a6adf739892a2016f3e1040a7a4a88463d5ad4451c
-  data.tar.gz: dd3fe763c52d4d79f90cd8629d0d6f758eff9cb4169a19acb4a0b759ada15f0262acf952fe193e22437088858652f7c8575133dd946e5e908d13dff149bf0a12
+  metadata.gz: cdc75de88ca87e840265127578e5692773e5d1d0d267db04e23ef981c6a052f8930b3e78de95ace33ccb6333fd669a5f11d23a2d41fbdc41938b2552ec8e6813
+  data.tar.gz: 13784bb1809523a32ae1c8372aaef7d1bec77ebb620a54be57fbb966c8c5946b8a92d55dee51cda81af2e2e59038accaadfa0b94c49376568c2fa65a51c5c1dc

data/README.md

@@ -0,0 +1,210 @@
+# Spree Emails
+
+[![Gem Version](https://badge.fury.io/rb/spree_emails.svg)](https://badge.fury.io/rb/spree_emails)
+
+Spree Emails provides transactional email templates and mailers for Spree Commerce, handling order confirmations, shipment notifications, and other customer communications.
+
+## Overview
+
+This gem includes:
+
+- **Order Mailer** - Order confirmation and cancellation emails
+- **Shipment Mailer** - Shipping and delivery notifications
+- **Reimbursement Mailer** - Refund notifications
+- **Event Subscribers** - Automatic email triggers on store events
+- **Email Templates** - Customizable HTML and text templates
+
+## Installation
+
+```bash
+bundle add spree_emails
+```
+
+## Email Types
+
+### Order Emails
+
+- **Order Confirmation** - Sent when an order is completed
+- **Order Cancellation** - Sent when an order is cancelled
+
+### Shipment Emails
+
+- **Shipment Notification** - Sent when a shipment is shipped
+- **Delivery Confirmation** - Sent when tracking shows delivered
+
+### Reimbursement Emails
+
+- **Refund Notification** - Sent when a reimbursement is processed
+
+## Configuration
+
+Transactional emails are controlled per-store via the `send_consumer_transactional_emails` preference. This can be configured in the admin dashboard under Store Settings, or programmatically:
+
+```ruby
+# Enable/disable transactional emails for a store
+store = Spree::Store.current
+store.update(send_consumer_transactional_emails: true)
+```
+
+The sender address is configured via the `mail_from_address` attribute on each store:
+
+```ruby
+store.update(mail_from_address: 'orders@example.com')
+```
+
+### Action Mailer Configuration
+
+```ruby
+# config/environments/production.rb
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings = {
+  address: 'smtp.example.com',
+  port: 587,
+  user_name: ENV['SMTP_USERNAME'],
+  password: ENV['SMTP_PASSWORD'],
+  authentication: 'plain',
+  enable_starttls_auto: true
+}
+```
+
+## Customization
+
+### Overriding Templates
+
+Copy email templates to your application:
+
+```bash
+# Copy all email templates
+cp -r $(bundle show spree_emails)/app/views/spree/mailer app/views/spree/
+
+# Or copy specific templates
+cp $(bundle show spree_emails)/app/views/spree/mailer/order_mailer/confirm_email.html.erb \
+   app/views/spree/mailer/order_mailer/
+```
+
+### Template Structure
+
+```
+app/views/spree/mailer/
+├── order_mailer/
+│   ├── confirm_email.html.erb
+│   ├── confirm_email.text.erb
+│   ├── cancel_email.html.erb
+│   └── cancel_email.text.erb
+├── shipment_mailer/
+│   ├── shipped_email.html.erb
+│   └── shipped_email.text.erb
+└── reimbursement_mailer/
+    ├── reimbursement_email.html.erb
+    └── reimbursement_email.text.erb
+```
+
+### Custom Mailer
+
+Create custom mailers by extending Spree's base mailer:
+
+```ruby
+# app/mailers/spree/order_mailer_decorator.rb
+module Spree
+  module OrderMailerDecorator
+    def confirm_email(order, resend = false)
+      @custom_data = fetch_custom_data(order)
+      super
+    end
+
+    private
+
+    def fetch_custom_data(order)
+      # Custom logic
+    end
+  end
+end
+
+Spree::OrderMailer.prepend(Spree::OrderMailerDecorator)
+```
+
+### Adding New Email Types
+
+```ruby
+# app/mailers/spree/custom_mailer.rb
+module Spree
+  class CustomMailer < BaseMailer
+    def welcome_email(user)
+      @user = user
+      mail(to: @user.email, subject: 'Welcome to our store!')
+    end
+  end
+end
+```
+
+## Event Integration
+
+Emails are triggered via Spree's event system. Create custom subscribers:
+
+```ruby
+# app/subscribers/spree/custom_email_subscriber.rb
+module Spree
+  module CustomEmailSubscriber
+    include Spree::Event::Subscriber
+
+    event_action :user_registered
+
+    def user_registered(event)
+      user = event.payload[:user]
+      Spree::CustomMailer.welcome_email(user).deliver_later
+    end
+  end
+end
+```
+
+## Disabling Emails
+
+Disable transactional emails for a specific store:
+
+```ruby
+store = Spree::Store.current
+store.update(send_consumer_transactional_emails: false)
+```
+
+This setting can also be managed in the admin dashboard under Store Settings.
+
+To disable all Spree transactional emails globally, remove this gem from your application:
+
+```bash
+bundle remove spree_emails
+```
+
+### Using Third-Party Email Services
+
+If you prefer to use a third-party email service like Klaviyo for transactional emails, you can use the [spree_klaviyo](https://github.com/spree/spree_klaviyo) extension. This allows you to leverage Klaviyo's email marketing platform for order confirmations, shipment notifications, and other transactional emails.
+
+## Testing
+
+Preview emails in development:
+
+```ruby
+# test/mailers/previews/spree/order_mailer_preview.rb
+module Spree
+  class OrderMailerPreview < ActionMailer::Preview
+    def confirm_email
+      order = Spree::Order.complete.last
+      Spree::OrderMailer.confirm_email(order)
+    end
+  end
+end
+```
+
+Visit `http://localhost:3000/rails/mailers/spree/order_mailer/confirm_email`
+
+Run the test suite:
+
+```bash
+cd emails
+bundle exec rake test_app  # First time only
+bundle exec rspec
+```
+
+## Documentation
+
+- [Email Customization Guide](https://docs.spreecommerce.org/developer/customization/emails)
+- [Events System](https://docs.spreecommerce.org/developer/core-concepts/events)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_emails
 version: !ruby/object:Gem::Version
-  version: 5.3.0.rc2
+  version: 5.3.0
 platform: ruby
 authors:
 - Sean Schofield
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.3.0.rc2
+        version: 5.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.3.0.rc2
+        version: 5.3.0
 - !ruby/object:Gem::Dependency
   name: email_spec
   requirement: !ruby/object:Gem::Requirement
@@ -47,6 +47,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE.md
+- README.md
 - Rakefile
 - app/assets/config/spree_emails_manifest.js
 - app/assets/images/logo/spree_50.png
@@ -99,9 +100,9 @@ licenses:
 - BSD-3-Clause
 metadata:
   bug_tracker_uri: https://github.com/spree/spree/issues
-  changelog_uri: https://github.com/spree/spree/releases/tag/v5.3.0.rc2
+  changelog_uri: https://github.com/spree/spree/releases/tag/v5.3.0
   documentation_uri: https://docs.spreecommerce.org/
-  source_code_uri: https://github.com/spree/spree/tree/v5.3.0.rc2
+  source_code_uri: https://github.com/spree/spree/tree/v5.3.0
 rdoc_options: []
 require_paths:
 - lib