email_digest 1.0.0

data/README.md

@@ -0,0 +1,253 @@
+# EmailDigest
+
+[![Gem Version](https://badge.fury.io/rb/email_digest.svg)](https://badge.fury.io/rb/email_digest)
+[![Build Status](https://github.com/yourusername/email_digest/workflows/CI/badge.svg)](https://github.com/yourusername/email_digest/actions)
+
+A flexible, production-ready email digest system for Rails applications. EmailDigest allows you to collect, summarize, and send batched email notifications to users with customizable schedules, priority-based processing, and multi-tenant support.
+
+## Features
+
+- ✅ **Multiple Digest Types**: Support for different types of digests (notifications, time logs, etc.)
+- ✅ **Flexible Scheduling**: Daily, weekly, or custom schedules with timezone support
+- ✅ **Priority-Based Processing**: High-priority items are highlighted in digests
+- ✅ **Smart Summarization**: Automatic grouping and summarization of digest items
+- ✅ **Multi-Tenant Support**: Full support for multi-tenant applications
+- ✅ **PostgreSQL**: Built on PostgreSQL with proper indexes and constraints
+- ✅ **Sidekiq Integration**: Asynchronous processing with Sidekiq
+- ✅ **Production Ready**: Includes error handling, logging, and monitoring hooks
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'email_digest'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install email_digest
+```
+
+## Setup
+
+### 1. Run the Install Generator
+
+```bash
+rails generate email_digest:install
+```
+
+This will:
+- Create `config/initializers/email_digest.rb`
+- Create a migration for the digest tables
+- Add the email_digest queue to your Sidekiq configuration
+- Add the scheduler cron job to your Sidekiq cron schedule
+
+### 2. Run the Migration
+
+```bash
+rails db:migrate
+```
+
+### 3. Configure EmailDigest
+
+Edit `config/initializers/email_digest.rb`:
+
+```ruby
+EmailDigest.configure do |config|
+  # Default settings
+  config.default_frequency = :daily
+  config.default_time = '09:00'
+  config.default_timezone = 'UTC'
+  config.queue_name = :email_digest
+  config.max_items_per_digest = 50
+  config.enable_summarization = true
+  config.mailer_class = 'UserMailer'
+  config.mailer_method = 'digest_email'
+  config.organization_class = 'Organization'
+  config.user_class = 'User'
+
+  # Register digest types
+  config.register_digest_type(:time_log_notifications, {
+    mailer_method: 'time_log_digest_email'
+  })
+
+  config.register_digest_type(:mentor_supervisor_notifications, {
+    mailer_method: 'mentor_supervisor_digest_email'
+  })
+end
+```
+
+### 4. Create Mailer Methods
+
+Add digest email methods to your mailer (e.g., `app/mailers/user_mailer.rb`):
+
+```ruby
+class UserMailer < ActionMailer::Base
+  def digest_email(user, summary, digest_type)
+    @user = user
+    @summary = summary.with_indifferent_access
+    @digest_type = digest_type
+    attach_logo
+    
+    I18n.with_locale(@user.default_language) do
+      mail(
+        to: @user.email,
+        from: 'no-reply@example.com',
+        subject: @summary[:subject] || 'Notifications Digest',
+        content_type: 'text/html'
+      ) do |format|
+        format.html { render 'digest_email' }
+      end
+    end
+  end
+end
+```
+
+### 5. Create Email Templates
+
+Create email templates in `app/views/user_mailer/`:
+
+```erb
+<!-- app/views/user_mailer/digest_email.html.erb -->
+<div style="background-color: #F5F5F5; padding: 20px;">
+  <div style="background-color: #FFFFFF; padding: 20px; max-width: 600px; margin: 0 auto;">
+    <h1><%= @summary[:subject] %></h1>
+    <p><%= @summary[:summary] %></p>
+    
+    <% if @summary[:grouped_items].present? %>
+      <% @summary[:grouped_items].each do |group_key, items| %>
+        <h2><%= group_key.to_s.humanize %> (<%= items.size %>)</h2>
+        <% items.each do |item| %>
+          <div style="margin: 10px 0; padding: 10px; border-left: 3px solid #007BFF;">
+            <h3><%= item[:subject] %></h3>
+            <p><%= truncate(item[:body], length: 200) %></p>
+          </div>
+        <% end %>
+      <% end %>
+    <% end %>
+  </div>
+</div>
+```
+
+## Usage
+
+### Adding Items to Digests
+
+#### Option 1: Using the Digestable Concern
+
+Include the concern in your models:
+
+```ruby
+class TimeLog < ActiveRecord::Base
+  include EmailDigest::Concerns::Digestable
+  
+  digestable :time_log_notifications
+end
+```
+
+Then add items to digests:
+
+```ruby
+time_log = TimeLog.find(1)
+time_log.add_to_digest(
+  user,
+  :submission_received,
+  subject: "New Time Log Submission",
+  body: "A new time log has been submitted for review.",
+  priority: 5,
+  metadata: { time_log_id: time_log.id }
+)
+```
+
+#### Option 2: Direct Creation
+
+```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 for review.",
+  priority: 5,
+  source_id: time_log.id.to_s,
+  source_type: 'TimeLog',
+  metadata: { time_log_id: time_log.id }
+)
+```
+
+### Managing User Preferences
+
+```ruby
+# Get or create a preference
+preference = EmailDigest::Models::DigestPreference.for_user_and_type(
+  user,
+  :time_log_notifications,
+  user.organization
+)
+
+# Update preference
+preference.update(
+  frequency: 'weekly',
+  day_of_week: 1, # Monday
+  time: '10:00',
+  timezone: 'America/New_York',
+  enabled: true
+)
+
+# Disable digest
+preference.update(enabled: false)
+```
+
+## Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `default_frequency` | `:daily` | Default digest frequency |
+| `default_time` | `'09:00'` | Default send time (HH:MM) |
+| `default_timezone` | `'UTC'` | Default timezone |
+| `queue_name` | `:email_digest` | Sidekiq queue name |
+| `max_items_per_digest` | `50` | Maximum items per digest |
+| `enable_summarization` | `true` | Enable smart summarization |
+| `mailer_class` | `'UserMailer'` | Mailer class name |
+| `mailer_method` | `'digest_email'` | Default mailer method |
+| `organization_class` | `'Organization'` | Organization model class |
+| `user_class` | `'User'` | User model class |
+
+## Requirements
+
+- Rails >= 6.0, < 8.0
+- PostgreSQL >= 10.0
+- Sidekiq >= 5.0
+- Sidekiq Cron >= 1.0
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+rails db:create db:migrate
+rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/email_digest.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Support
+
+For issues, questions, or contributions, please visit:
+- [GitHub Issues](https://github.com/yourusername/email_digest/issues)
+- [Documentation](https://github.com/yourusername/email_digest/wiki)

data/REPOSITORY_READY.md

@@ -0,0 +1,146 @@
+# ✅ EmailDigest Gem Repository - Ready!
+
+## Location
+
+Your gem repository is now at:
+```
+/Users/rosharma/workspace/email_digest
+```
+
+This is parallel to your main application at:
+```
+/Users/rosharma/workspace/sll-la/eportfolio
+```
+
+## What's Included
+
+✅ Complete gem structure with all source files
+✅ Generator for easy installation
+✅ Gemspec ready for RubyGems
+✅ Complete documentation
+✅ Publishing guides
+
+## Next Steps
+
+### 1. Initialize Git (if needed)
+
+```bash
+cd /Users/rosharma/workspace/email_digest
+git init
+git add .
+git commit -m "Initial commit: EmailDigest gem v1.0.0"
+```
+
+### 2. Update Gemspec Metadata
+
+Edit `email_digest.gemspec` and update:
+- `spec.authors` - Your name
+- `spec.email` - Your email
+- `spec.homepage` - Your GitHub repo URL
+- `spec.metadata` URLs - Your repository URLs
+
+### 3. Create GitHub Repository
+
+```bash
+# Create repo on GitHub, then:
+git remote add origin https://github.com/yourusername/email_digest.git
+git branch -M main
+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 Application
+
+In your main app's `Gemfile` (`/Users/rosharma/workspace/sll-la/eportfolio/Gemfile`):
+
+```ruby
+# Option 1: Local path (for development)
+gem 'email_digest', path: '../../email_digest'
+
+# Option 2: From GitHub (after pushing)
+gem 'email_digest', git: 'https://github.com/yourusername/email_digest.git'
+
+# Option 3: From RubyGems (after publishing)
+gem 'email_digest'
+```
+
+Then:
+
+```bash
+cd /Users/rosharma/workspace/sll-la/eportfolio
+bundle install
+rails generate email_digest:install
+rails db:migrate
+```
+
+## File Structure
+
+```
+email_digest/
+├── email_digest.gemspec          # Gem specification
+├── README.md                      # Main documentation
+├── LICENSE.txt                    # MIT License
+├── CHANGELOG.md                   # Version history
+├── QUICK_START.md                 # Quick setup guide
+├── RUBYGEMS_PUBLISHING.md         # Publishing guide
+├── COMPLETE_SETUP_INSTRUCTIONS.md # Detailed setup
+└── lib/
+    ├── email_digest.rb            # Main entry point
+    └── email_digest/
+        ├── version.rb
+        ├── configuration.rb
+        ├── railtie.rb
+        ├── models/
+        │   ├── digest_item.rb
+        │   └── digest_preference.rb
+        ├── services/
+        │   ├── digest_collector.rb
+        │   ├── digest_summarizer.rb
+        │   └── digest_scheduler.rb
+        ├── workers/
+        │   ├── digest_processor_worker.rb
+        │   ├── digest_sender_worker.rb
+        │   └── digest_scheduler_worker.rb
+        ├── concerns/
+        │   └── digestable.rb
+        └── generators/
+            └── email_digest/
+                └── install/
+                    ├── install_generator.rb
+                    └── templates/
+                        ├── email_digest.rb
+                        ├── create_email_digest_tables.rb
+                        └── README
+```
+
+## Important Notes
+
+✅ **Separate Repository** - Completely independent from your main app
+✅ **Ready to Publish** - All files configured for RubyGems
+✅ **No Disruption** - Your main app continues to work normally
+✅ **Easy Integration** - Just add to Gemfile when ready
+
+## Documentation
+
+- `QUICK_START.md` - 5-minute setup guide
+- `COMPLETE_SETUP_INSTRUCTIONS.md` - Detailed step-by-step
+- `RUBYGEMS_PUBLISHING.md` - Complete publishing guide
+- `README.md` - Full usage documentation
+
+## Status
+
+🎉 **Your gem repository is ready!**
+
+You can now:
+1. Initialize git and push to GitHub
+2. Update gemspec metadata
+3. Publish to RubyGems
+4. Use in your application via Gemfile

data/RUBYGEMS_PUBLISHING.md

@@ -0,0 +1,272 @@
+# Publishing EmailDigest to RubyGems
+
+Complete guide for publishing and maintaining your gem on RubyGems.
+
+## Prerequisites
+
+1. **Create RubyGems Account**
+   - Go to https://rubygems.org
+   - Sign up for a free account
+   - Verify your email
+
+2. **Get API Key**
+   - Go to https://rubygems.org/profile/edit
+   - Scroll to "API Access"
+   - Create a new API key
+   - Copy the key (you'll use it once)
+
+## Initial Setup
+
+### 1. Configure RubyGems Credentials
+
+```bash
+# Set your credentials (one-time setup)
+gem signin
+# Enter your RubyGems username and password
+# This creates ~/.gem/credentials
+```
+
+Or manually create `~/.gem/credentials`:
+
+```yaml
+---
+:rubygems_api_key: YOUR_API_KEY_HERE
+```
+
+### 2. Update Gemspec
+
+Make sure `email_digest.gemspec` has correct metadata:
+
+```ruby
+spec.name          = 'email_digest'
+spec.version       = EmailDigest::VERSION
+spec.authors       = ['Your Name']  # Update this
+spec.email         = ['your.email@example.com']  # Update this
+spec.homepage      = 'https://github.com/yourusername/email_digest'  # Update this
+```
+
+## Publishing Process
+
+### Step 1: Prepare Your Gem
+
+```bash
+# Make sure you're in the gem directory
+cd ~/workspace/email_digest
+
+# Check your files
+git status
+
+# Update version if needed (in lib/email_digest/version.rb)
+# Update CHANGELOG.md
+
+# Commit changes
+git add .
+git commit -m "Prepare for release v1.0.0"
+```
+
+### Step 2: Build the Gem
+
+```bash
+# Build the gem
+gem build email_digest.gemspec
+
+# This creates: email_digest-1.0.0.gem
+# Verify the file was created
+ls -lh *.gem
+```
+
+### Step 3: Test Locally (Optional but Recommended)
+
+```bash
+# Install locally to test
+gem install ./email_digest-1.0.0.gem
+
+# Or test in a Rails app
+# In Gemfile: gem 'email_digest', path: '../email_digest'
+```
+
+### Step 4: Push to GitHub
+
+```bash
+# Tag the release
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin main
+git push origin v1.0.0
+```
+
+### Step 5: Publish to RubyGems
+
+```bash
+# Push to RubyGems
+gem push email_digest-1.0.0.gem
+
+# You'll see:
+# Pushing gem to https://rubygems.org...
+# Successfully registered gem: email_digest
+```
+
+### Step 6: Verify Publication
+
+```bash
+# Check on RubyGems
+# Visit: https://rubygems.org/gems/email_digest
+
+# Or via command line
+gem search email_digest
+gem info email_digest
+```
+
+## Updating the Gem
+
+### For Bug Fixes (Patch Version: 1.0.0 → 1.0.1)
+
+```bash
+# 1. Update version
+# In lib/email_digest/version.rb: VERSION = '1.0.1'
+
+# 2. Update CHANGELOG.md
+
+# 3. Commit
+git add .
+git commit -m "Bump version to 1.0.1"
+
+# 4. Tag
+git tag -a v1.0.1 -m "Version 1.0.1"
+git push origin main
+git push origin v1.0.1
+
+# 5. Build and push
+gem build email_digest.gemspec
+gem push email_digest-1.0.1.gem
+```
+
+### For New Features (Minor Version: 1.0.0 → 1.1.0)
+
+```bash
+# Same process, but update to 1.1.0
+```
+
+### For Breaking Changes (Major Version: 1.0.0 → 2.0.0)
+
+```bash
+# Same process, but update to 2.0.0
+# Make sure to document breaking changes in CHANGELOG
+```
+
+## Versioning Guidelines
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (1.0.0 → 2.0.0): Incompatible API changes
+- **MINOR** (1.0.0 → 1.1.0): New functionality, backwards compatible
+- **PATCH** (1.0.0 → 1.0.1): Bug fixes, backwards compatible
+
+## Best Practices
+
+### Before Publishing
+
+- [ ] Update version number
+- [ ] Update CHANGELOG.md
+- [ ] Run tests (if you have them)
+- [ ] Test installation in a clean environment
+- [ ] Test generator: `rails generate email_digest:install`
+- [ ] Verify all dependencies are correct
+- [ ] Check gemspec metadata
+
+### After Publishing
+
+- [ ] Verify gem appears on RubyGems.org
+- [ ] Test installation: `gem install email_digest`
+- [ ] Test in a fresh Rails app
+- [ ] Update GitHub release notes
+- [ ] Announce on relevant channels (if applicable)
+
+## Troubleshooting
+
+### "You have already pushed this version"
+
+If you try to push the same version twice:
+
+```bash
+# Update version and try again
+# Or yank the version first (if needed)
+gem yank email_digest -v 1.0.0
+```
+
+### "Authentication required"
+
+```bash
+# Re-authenticate
+gem signin
+```
+
+### "Invalid gemspec"
+
+```bash
+# Validate your gemspec
+gem spec email_digest.gemspec
+
+# Check for syntax errors
+ruby -c email_digest.gemspec
+```
+
+## Yanking a Version (Removing)
+
+If you need to remove a published version:
+
+```bash
+# Yank a specific version
+gem yank email_digest -v 1.0.0
+
+# Note: This doesn't delete it, just marks it as yanked
+# Users who already installed it can still use it
+```
+
+## Using Your Published Gem
+
+Once published, others can use it:
+
+```ruby
+# In Gemfile
+gem 'email_digest'
+
+# Then
+bundle install
+rails generate email_digest:install
+rails db:migrate
+```
+
+## Maintenance
+
+### Regular Updates
+
+- Keep dependencies updated
+- Monitor for security vulnerabilities
+- Respond to issues on GitHub
+- Update documentation as needed
+
+### Release Checklist Template
+
+```markdown
+## Release Checklist
+
+- [ ] Update version in lib/email_digest/version.rb
+- [ ] Update CHANGELOG.md
+- [ ] Run tests
+- [ ] Update README if needed
+- [ ] Commit changes
+- [ ] Create git tag
+- [ ] Build gem
+- [ ] Test gem installation
+- [ ] Push to GitHub
+- [ ] Publish to RubyGems
+- [ ] Verify on RubyGems.org
+- [ ] Create GitHub release
+```
+
+## Resources
+
+- RubyGems: https://rubygems.org
+- RubyGems Guides: https://guides.rubygems.org
+- Semantic Versioning: https://semver.org
+- Bundler Best Practices: https://bundler.io/v2.0/guides/creating_gem.html