email_digest 1.0.0

data/CUSTOMIZATION_GUIDE.md

@@ -0,0 +1,264 @@
+# EmailDigest Customization Guide
+
+This guide explains how to customize the email digest system for your specific needs.
+
+## Answers to Common Questions
+
+### 1. Will it trigger if only 1 digest_item is present?
+
+**Yes!** The system triggers if there are **any items** (1 or more). Looking at `digest_scheduler.rb`:
+
+```ruby
+if items.any?  # This means 1 or more items will trigger
+  Workers::DigestProcessorWorker.perform_async(...)
+end
+```
+
+So if you have even 1 digest item, it will be processed and sent.
+
+### 2. How is the email context generated?
+
+The email context comes from the `DigestSummarizer` which creates a summary hash. You can customize this per `digest_type` by creating custom summarizer classes in your application.
+
+### 3. How are digest_types, users, and organizations combined?
+
+The scheduler runs every 15 minutes and:
+1. Finds all `DigestPreference` records where `next_send_at <= now` and `enabled = true`
+2. Each preference is unique per `(user_id, digest_type, organization_id)`
+3. For each preference, it collects pending items for that specific user+digest_type+organization
+4. Processes and sends them together
+
+So each email contains items for:
+- **One user**
+- **One digest_type** (e.g., `time_log_notifications`)
+- **One organization**
+
+### 4. How to store additional information (course, section, groupTemplate, group)?
+
+Use the `metadata` field (JSONB) in `DigestItem`. It can store any additional context you need.
+
+## Customization Examples
+
+### Example 1: Custom Summarizer with Course/Section Context
+
+Create a custom summarizer in your app:
+
+```ruby
+# app/services/email_digest/summarizers/time_log_summarizer.rb
+module EmailDigest
+  module Summarizers
+    class TimeLogSummarizer < EmailDigest::Services::DigestSummarizer
+      private
+
+      def enrich_item_hash(item_hash, item)
+        metadata = item.metadata || {}
+        
+        # Load additional context from metadata
+        item_hash.merge(
+          course: load_course(metadata['course_id']),
+          section: load_section(metadata['section_id']),
+          group_template: load_group_template(metadata['group_template_id']),
+          group: load_group(metadata['group_id']),
+          time_log: load_time_log(item.source_id) if item.source_id
+        )
+      end
+
+      def load_course(course_id)
+        return nil unless course_id
+        # Your logic to load course
+        Course.find(course_id) rescue nil
+      end
+
+      def load_section(section_id)
+        return nil unless section_id
+        # Your logic to load section
+        Section.find(section_id) rescue nil
+      end
+
+      def load_group_template(group_template_id)
+        return nil unless group_template_id
+        # Your logic to load group template
+        GroupTemplate.find(group_template_id) rescue nil
+      end
+
+      def load_group(group_id)
+        return nil unless group_id
+        # Your logic to load group
+        Group.find(group_id) rescue nil
+      end
+
+      def load_time_log(time_log_id)
+        return nil unless time_log_id
+        TimeLog.find(time_log_id) rescue nil
+      end
+
+      # Override summary generation if needed
+      def single_item_summary
+        item = items.first
+        item_hash = enrich_item_hash(item_to_hash(item), item)
+        
+        # Custom subject with course/section info
+        subject = if item_hash[:course] && item_hash[:section]
+          "#{item.subject} - #{item_hash[:course].name} (#{item_hash[:section].name})"
+        else
+          item.subject || "New #{item.notification_type.humanize}"
+        end
+
+        {
+          subject: subject,
+          summary: item.body,
+          items: [item_hash],
+          grouped_items: { item.notification_type => [item_hash] },
+          total_count: 1
+        }
+      end
+    end
+  end
+end
+```
+
+### Example 2: Register Custom Summarizer
+
+In your `config/initializers/email_digest.rb`:
+
+```ruby
+EmailDigest.configure do |config|
+  # ... other config ...
+
+  config.register_digest_type(:time_log_notifications, {
+    mailer_method: 'time_log_digest_email',
+    summarizer: 'EmailDigest::Summarizers::TimeLogSummarizer'  # Custom summarizer
+  })
+
+  config.register_digest_type(:mentor_supervisor_notifications, {
+    mailer_method: 'mentor_supervisor_digest_email',
+    summarizer: 'EmailDigest::Summarizers::MentorSupervisorSummarizer'  # Another custom summarizer
+  })
+end
+```
+
+### Example 3: Storing Additional Context in DigestItem
+
+When creating digest items, include additional context in metadata:
+
+```ruby
+# In your application code
+EmailDigest::Models::DigestItem.create_for_user(
+  user,
+  :time_log_notifications,
+  :submission_received,
+  subject: "New Time Log Submission",
+  body: "A new time log has been submitted for review.",
+  priority: 5,
+  source_id: time_log.id.to_s,
+  source_type: 'TimeLog',
+  metadata: {
+    course_id: time_log.course.id.to_s,
+    course_name: time_log.course.name,
+    section_id: time_log.section.id.to_s,
+    section_name: time_log.section.name,
+    group_template_id: time_log.group_template&.id&.to_s,
+    group_template_name: time_log.group_template&.name,
+    group_id: time_log.group.id.to_s,
+    group_name: time_log.group.name,
+    student_name: time_log.student.name,
+    # ... any other context you need
+  }
+)
+```
+
+Or using the Digestable concern:
+
+```ruby
+class TimeLog < ActiveRecord::Base
+  include EmailDigest::Concerns::Digestable
+  digestable :time_log_notifications
+
+  def add_to_digest(user, notification_type, options = {})
+    super(user, notification_type, {
+      metadata: {
+        course_id: course.id.to_s,
+        course_name: course.name,
+        section_id: section.id.to_s,
+        section_name: section.name,
+        group_template_id: group_template&.id&.to_s,
+        group_id: group.id.to_s,
+        group_name: group.name,
+        # Merge with any existing metadata
+      }.merge(options[:metadata] || {})
+    }.merge(options))
+  end
+end
+```
+
+### Example 4: Custom Mailer with Rich Context
+
+In your mailer, you'll receive the enriched summary:
+
+```ruby
+class UserMailer < ActionMailer::Base
+  def time_log_digest_email(user, summary, digest_type)
+    @user = user
+    @summary = summary.with_indifferent_access
+    @digest_type = digest_type
+    
+    # Now you have access to enriched items with course/section/group info
+    @items = @summary[:items]  # Each item has course, section, group_template, group, etc.
+    
+    mail(
+      to: @user.email,
+      from: 'no-reply@example.com',
+      subject: @summary[:subject],
+      content_type: 'text/html'
+    ) do |format|
+      format.html { render 'time_log_digest_email' }
+    end
+  end
+end
+```
+
+In your email template:
+
+```erb
+<!-- app/views/user_mailer/time_log_digest_email.html.erb -->
+<% @summary[:items].each do |item| %>
+  <div>
+    <h3><%= item[:subject] %></h3>
+    <p><%= item[:body] %></p>
+    
+    <% if item[:course] %>
+      <p><strong>Course:</strong> <%= item[:course][:name] %></p>
+    <% end %>
+    
+    <% if item[:section] %>
+      <p><strong>Section:</strong> <%= item[:section][:name] %></p>
+    <% end %>
+    
+    <% if item[:group_template] %>
+      <p><strong>Group Template:</strong> <%= item[:group_template][:name] %></p>
+    <% end %>
+    
+    <% if item[:group] %>
+      <p><strong>Group:</strong> <%= item[:group][:name] %></p>
+    <% end %>
+  </div>
+<% end %>
+```
+
+## How the 15-Minute Scheduler Works
+
+1. **Every 15 minutes**, `DigestSchedulerWorker` runs (configured in `sidekiq_cron_schedule.yml`)
+2. It calls `DigestScheduler.process_all_ready(organization)`
+3. For each `DigestPreference` that's ready (`next_send_at <= now`):
+   - Loads the user and organization
+   - Uses `DigestCollector` (or custom collector) to gather pending items
+   - If items exist (1 or more), enqueues `DigestProcessorWorker`
+   - If no items, just updates the schedule
+
+## Summary
+
+- ✅ **Triggers with 1+ items** - Yes, any items will trigger
+- ✅ **Customizable per digest_type** - Create custom summarizers in your app
+- ✅ **Metadata support** - Store course, section, groupTemplate, group, etc. in metadata
+- ✅ **Rich context in emails** - Custom summarizers can enrich items with additional data
+- ✅ **Application-level control** - All customization happens in your app, not the gem

data/FAQ.md

@@ -0,0 +1,133 @@
+# EmailDigest FAQ
+
+## Common Questions
+
+### Q1: Will it trigger if only 1 digest_item is present?
+
+**A: Yes!** The system triggers if there are **any items** (1 or more). 
+
+Looking at the code in `digest_scheduler.rb`:
+```ruby
+if items.any?  # This means 1 or more items will trigger
+  Workers::DigestProcessorWorker.perform_async(...)
+end
+```
+
+So even a single digest item will be processed and sent.
+
+### Q2: What context is being sent to users in mail?
+
+**A:** The context comes from the `DigestSummarizer` which creates a summary hash containing:
+- `subject` - Email subject
+- `summary` - Summary text
+- `items` - Array of all items
+- `grouped_items` - Items grouped by notification_type
+- `total_count` - Total number of items
+
+Each item in the summary includes:
+- `id`, `notification_type`, `subject`, `body`
+- `metadata` - JSONB field that can contain any additional data
+- `source_id`, `source_type`, `priority`, `created_at`
+
+**You can customize this per digest_type** by creating custom summarizer classes in your application (see `CUSTOMIZATION_GUIDE.md`).
+
+### Q3: How are different digest_types, users, and organizations combined?
+
+**A:** The scheduler runs every 15 minutes and processes them separately:
+
+1. Finds all `DigestPreference` records where:
+   - `next_send_at <= now`
+   - `enabled = true`
+   - Optionally filtered by `organization_id`
+
+2. Each preference is unique per `(user_id, digest_type, organization_id)`
+
+3. For each preference:
+   - Collects pending items for that specific user+digest_type+organization
+   - Processes them together
+   - Sends one email per preference
+
+**So each email contains items for:**
+- One user
+- One digest_type (e.g., `time_log_notifications`)
+- One organization
+
+Items are NOT combined across different digest_types or users.
+
+### Q4: How to store additional information (course, section, groupTemplate, group) in digest_item?
+
+**A:** Use the `metadata` field (JSONB) in `DigestItem`. It can store any additional context:
+
+```ruby
+EmailDigest::Models::DigestItem.create_for_user(
+  user,
+  :time_log_notifications,
+  :submission_received,
+  subject: "New Time Log Submission",
+  body: "A new time log has been submitted.",
+  metadata: {
+    course_id: course.id.to_s,
+    course_name: course.name,
+    section_id: section.id.to_s,
+    section_name: section.name,
+    group_template_id: group_template.id.to_s,
+    group_id: group.id.to_s,
+    group_name: group.name,
+    # ... any other data you need
+  }
+)
+```
+
+Then in your custom summarizer, you can access and enrich this data:
+
+```ruby
+def enrich_item_hash(item_hash, item)
+  metadata = item.metadata || {}
+  item_hash.merge(
+    course: load_course(metadata['course_id']),
+    section: load_section(metadata['section_id']),
+    group_template: load_group_template(metadata['group_template_id']),
+    group: load_group(metadata['group_id'])
+  )
+end
+```
+
+### Q5: How to customize email content per digest_type?
+
+**A:** Create custom summarizer classes in your application:
+
+1. Create a custom summarizer:
+```ruby
+# app/services/email_digest/summarizers/time_log_summarizer.rb
+module EmailDigest
+  module Summarizers
+    class TimeLogSummarizer < EmailDigest::Services::DigestSummarizer
+      # Override methods to customize behavior
+    end
+  end
+end
+```
+
+2. Register it in your initializer:
+```ruby
+EmailDigest.configure do |config|
+  config.register_digest_type(:time_log_notifications, {
+    mailer_method: 'time_log_digest_email',
+    summarizer: 'EmailDigest::Summarizers::TimeLogSummarizer'
+  })
+end
+```
+
+See `CUSTOMIZATION_GUIDE.md` for detailed examples.
+
+### Q6: What runs at 15-minute intervals?
+
+**A:** The `DigestSchedulerWorker` runs every 15 minutes (configured in `sidekiq_cron_schedule.yml`). It:
+
+1. Finds all preferences ready to send
+2. For each preference:
+   - Collects pending items
+   - If items exist, processes them
+   - Updates the schedule for next send
+
+This ensures digests are sent according to each user's schedule (daily, weekly, etc.).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 EmailDigest Contributors
+
+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/QUICK_START.md

@@ -0,0 +1,62 @@
+# Quick Start - EmailDigest Gem Repository
+
+## 🚀 Create Your Gem Repository in 5 Minutes
+
+### 1. Create Directory & Copy Files
+
+```bash
+cd ~/workspace
+mkdir email_digest
+cd email_digest
+cp -r /Users/rosharma/workspace/sll-la/eportfolio/gem_package/* .
+git init
+```
+
+### 2. Update Gemspec
+
+Edit `email_digest.gemspec` - update author, email, and GitHub URLs.
+
+### 3. Push to GitHub
+
+```bash
+git add .
+git commit -m "Initial commit"
+git remote add origin https://github.com/yourusername/email_digest.git
+git push -u origin main
+```
+
+### 4. Publish to RubyGems
+
+```bash
+# Create account at https://rubygems.org
+gem signin
+gem build email_digest.gemspec
+gem push email_digest-1.0.0.gem
+```
+
+### 5. Use in Your App
+
+```ruby
+# In Gemfile
+gem 'email_digest'
+```
+
+```bash
+bundle install
+rails generate email_digest:install
+rails db:migrate
+```
+
+## 📚 Full Documentation
+
+- `COMPLETE_SETUP_INSTRUCTIONS.md` - Detailed setup guide
+- `RUBYGEMS_PUBLISHING.md` - Publishing guide
+- `README.md` - Usage documentation
+
+## ✅ Done!
+
+Your gem is now:
+- ✅ Separate from your main app
+- ✅ Available via Gemfile
+- ✅ Published to RubyGems (after Step 4)
+- ✅ Ready for others to use