email_digest 1.0.0

data/SETUP_SEPARATE_GEM_REPO.md

@@ -0,0 +1,131 @@
+# Setup Separate EmailDigest Gem Repository
+
+This guide will help you create a completely separate gem repository that you can publish to RubyGems.
+
+## Step 1: Create New Repository Directory
+
+```bash
+# Navigate to where you want the gem repo (outside your main app)
+cd ~/workspace  # or any location you prefer
+mkdir email_digest
+cd email_digest
+git init
+```
+
+## Step 2: Copy All Files from gem_package
+
+```bash
+# Copy everything from gem_package to your new repo
+cp -r /Users/rosharma/workspace/sll-la/eportfolio/gem_package/* ~/workspace/email_digest/
+```
+
+## Step 3: 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['source_code_uri']` - Your GitHub repo
+- `spec.metadata['changelog_uri']` - Your CHANGELOG URL
+
+## Step 4: Create GitHub Repository
+
+```bash
+# Create a new repo on GitHub (via web or CLI)
+# Then connect it:
+git remote add origin https://github.com/rohitsharma170801/email_digest.git
+git add .
+git commit -m "Initial commit"
+git branch -M main
+git push -u origin main
+```
+
+## Step 5: Test the Gem Locally
+
+```bash
+# Build the gem
+gem build email_digest.gemspec
+
+# Test installation
+gem install ./email_digest-1.0.0.gem
+
+# Or test in your app
+# In your app's Gemfile:
+# gem 'email_digest', path: '../email_digest'
+```
+
+## Step 6: Publish to RubyGems
+
+```bash
+# 1. Create account at https://rubygems.org
+# 2. Get your API key from https://rubygems.org/profile/edit
+
+# 3. Build and push
+gem build email_digest.gemspec
+gem push email_digest-1.0.0.gem
+
+# Or use your API key
+gem push email_digest-1.0.0.gem --key your_api_key_name
+```
+
+## Step 7: Use in Your Application
+
+In your main app's `Gemfile`:
+
+```ruby
+# From RubyGems (after publishing)
+gem 'email_digest'
+
+# Or from GitHub (before publishing)
+gem 'email_digest', git: 'https://github.com/yourusername/email_digest.git'
+
+# Or local development
+gem 'email_digest', path: '../email_digest'
+```
+
+Then:
+
+```bash
+bundle install
+rails generate email_digest:install
+rails db:migrate
+```
+
+## File Checklist
+
+Make sure your gem repo has:
+- ✅ `email_digest.gemspec`
+- ✅ `lib/email_digest.rb`
+- ✅ `lib/email_digest/version.rb`
+- ✅ `lib/email_digest/configuration.rb`
+- ✅ `lib/email_digest/railtie.rb`
+- ✅ All models, services, workers, concerns
+- ✅ Generator files
+- ✅ `README.md`
+- ✅ `LICENSE.txt`
+- ✅ `CHANGELOG.md`
+- ✅ `.gitignore`
+
+## Publishing Checklist
+
+Before publishing:
+- [ ] Update version in `lib/email_digest/version.rb`
+- [ ] Update `CHANGELOG.md`
+- [ ] Update gemspec metadata
+- [ ] Test gem build: `gem build email_digest.gemspec`
+- [ ] Test installation locally
+- [ ] Test in a test Rails app
+- [ ] Push to GitHub
+- [ ] Publish to RubyGems
+
+## Version Updates
+
+When updating the gem:
+
+1. Update version in `lib/email_digest/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Create git tag: `git tag -a v1.0.1 -m "Version 1.0.1"`
+5. Push tag: `git push origin v1.0.1`
+6. Build: `gem build email_digest.gemspec`
+7. Push: `gem push email_digest-1.0.1.gem`

data/email_digest.gemspec

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative 'lib/email_digest/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'email_digest'
+  spec.version       = EmailDigest::VERSION
+  spec.authors       = ['Rohit sharma']
+  spec.email         = ['rohitsharma170801@gmail.com']
+
+  spec.summary       = 'A flexible, production-ready email digest system for Rails applications'
+  spec.description   = <<~DESC
+    EmailDigest is a comprehensive email digest system that allows you to collect,
+    summarize, and send batched email notifications to users. It supports multiple
+    digest types, customizable schedules, priority-based processing, and multi-tenant
+    architectures. Built with PostgreSQL and Sidekiq for reliability and scalability.
+  DESC
+  spec.homepage      = 'https://github.com/rohitsharma170801/email_digest'
+  spec.license       = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/rohitsharma170801/email_digest'
+  spec.metadata['changelog_uri'] = 'https://github.com/rohitsharma170801/email_digest/blob/main/CHANGELOG.md'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Dependencies
+  spec.add_dependency 'rails', '>= 6.0', '< 8.0'
+  spec.add_dependency 'sidekiq', '>= 5.0'
+  spec.add_dependency 'sidekiq-cron', '>= 1.0'
+  spec.add_dependency 'pg', '>= 1.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec-rails', '~> 6.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'rubocop-rails', '~> 2.0'
+  spec.add_development_dependency 'simplecov', '~> 0.21'
+end

data/lib/email_digest/concerns/digestable.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  module Concerns
+    module Digestable
+      extend ActiveSupport::Concern
+
+      included do
+        # This concern can be included in models that want to support digest notifications
+      end
+
+      module ClassMethods
+        def digestable(digest_type, options = {})
+          @digest_type = digest_type
+          @digest_options = options
+        end
+
+        def digest_type
+          @digest_type
+        end
+
+        def digest_options
+          @digest_options || {}
+        end
+      end
+
+      def add_to_digest(user, notification_type, options = {})
+        digest_type = self.class.digest_type || options[:digest_type]
+        return unless digest_type
+
+        # Get organization from user or options
+        organization = options[:organization] || user.organization
+
+        EmailDigest::Models::DigestItem.create_for_user(
+          user,
+          digest_type,
+          notification_type,
+          {
+            subject: options[:subject],
+            body: options[:body],
+            metadata: options[:metadata] || {},
+            source_id: id.to_s,
+            source_type: self.class.name,
+            priority: options[:priority] || 0,
+            organization: organization
+          }.merge(options)
+        )
+      end
+
+      def add_to_digest_for_users(users, notification_type, options = {})
+        users.each do |user|
+          add_to_digest(user, notification_type, options)
+        end
+      end
+    end
+  end
+end

data/lib/email_digest/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  class Configuration
+    attr_accessor :default_frequency,
+                  :default_time,
+                  :default_timezone,
+                  :queue_name,
+                  :max_items_per_digest,
+                  :enable_summarization,
+                  :mailer_class,
+                  :mailer_method,
+                  :organization_class,
+                  :user_class,
+                  :digest_types
+
+    def initialize
+      @default_frequency = :daily
+      @default_time = '09:00'
+      @default_timezone = 'UTC'
+      @queue_name = :email_digest
+      @max_items_per_digest = 50
+      @enable_summarization = true
+      @mailer_class = 'UserMailer'
+      @mailer_method = 'digest_email'
+      @organization_class = 'Organization'
+      @user_class = 'User'
+      @digest_types = {}
+    end
+
+    def register_digest_type(type_name, options = {})
+      @digest_types[type_name.to_sym] = {
+        collector: options[:collector] || "EmailDigest::Collectors::#{type_name.to_s.classify}Collector",
+        summarizer: options[:summarizer] || "EmailDigest::Summarizers::#{type_name.to_s.classify}Summarizer",
+        mailer_method: options[:mailer_method] || "digest_#{type_name}_email"
+      }
+    end
+  end
+end
+

data/lib/email_digest/generators/email_digest/install/install_generator.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Installs EmailDigest and generates the necessary configuration files'
+
+      def create_initializer
+        template 'email_digest.rb', 'config/initializers/email_digest.rb'
+      end
+
+      def create_migration
+        migration_template 'create_email_digest_tables.rb',
+                          'db/migrate/create_email_digest_tables.rb'
+      end
+
+      def add_sidekiq_queue
+        if File.exist?('config/sidekiq.yml')
+          inject_into_file 'config/sidekiq.yml', after: ":queues:\n" do
+            "  - email_digest\n"
+          end
+        else
+          say_status 'warning', 'config/sidekiq.yml not found. Please add email_digest to your Sidekiq queues manually.', :yellow
+        end
+      end
+
+      def add_sidekiq_cron_job
+        if File.exist?('config/sidekiq_cron_schedule.yml')
+          inject_into_file 'config/sidekiq_cron_schedule.yml', after: "# sidekiq-cron will make sure only one cron job will be inserted into queue\n" do
+            <<~YAML
+
+              email_digest_scheduler_worker:
+                cron: "*/15 * * * *" # every 15 minutes
+                class: "EmailDigest::Workers::DigestSchedulerWorker"
+                queue: email_digest
+            YAML
+          end
+        else
+          say_status 'warning', 'config/sidekiq_cron_schedule.yml not found. Please add the scheduler job manually.', :yellow
+        end
+      end
+
+      def show_readme
+        readme 'README' if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/email_digest/generators/email_digest/install/templates/README

@@ -0,0 +1,16 @@
+EmailDigest has been successfully installed!
+
+Next steps:
+
+1. Run the migration:
+   rails db:migrate
+
+2. Configure your digest types in config/initializers/email_digest.rb
+
+3. Add digest_email method to your mailer (e.g., app/mailers/user_mailer.rb)
+
+4. Include EmailDigest::Concerns::Digestable in models that should create digest items
+
+5. Start Sidekiq to process digest jobs
+
+For more information, visit: https://github.com/yourusername/email_digest

data/lib/email_digest/generators/email_digest/install/templates/create_email_digest_tables.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class CreateEmailDigestTables < ActiveRecord::Migration[7.2]
+  def change
+    create_table :email_digest_items do |t|
+      t.string :user_id, null: false
+      t.string :organization_id, null: false
+      t.string :digest_type, null: false
+      t.string :notification_type, null: false
+      t.string :subject
+      t.text :body
+      t.jsonb :metadata, default: {}
+      t.string :source_id # ID of the source object (e.g., time_log_id)
+      t.string :source_type # Type of source object
+      t.integer :priority, default: 0, null: false
+      t.boolean :processed, default: false, null: false
+      t.datetime :processed_at
+
+      t.timestamps
+    end
+
+    create_table :email_digest_preferences do |t|
+      t.string :user_id, null: false
+      t.string :organization_id, null: false
+      t.string :digest_type, null: false
+      t.boolean :enabled, default: true, null: false
+      t.string :frequency, default: 'daily', null: false # daily, weekly, custom
+      t.integer :day_of_week # 0-6 (Sunday-Saturday) for weekly
+      t.string :time, default: '09:00', null: false # HH:MM format
+      t.string :timezone, default: 'UTC', null: false
+      t.jsonb :custom_schedule # For complex schedules
+      t.datetime :last_sent_at
+      t.datetime :next_send_at
+
+      t.timestamps
+    end
+
+    # Indexes for email_digest_items
+    add_index :email_digest_items, [:user_id, :digest_type, :processed, :organization_id], 
+              name: 'index_digest_items_on_user_digest_processed_org'
+    add_index :email_digest_items, [:organization_id, :processed, :created_at], 
+              name: 'index_digest_items_on_org_processed_created'
+    add_index :email_digest_items, [:source_id, :source_type], 
+              name: 'index_digest_items_on_source'
+    # Optimized index for DigestCollector queries (pending items sorted by priority and created_at)
+    # Partial index for better performance (only indexes unprocessed items)
+    execute <<-SQL
+      CREATE INDEX index_digest_items_collector_query 
+      ON email_digest_items (user_id, digest_type, organization_id, created_at DESC, priority DESC)
+      WHERE processed = false;
+    SQL
+    add_index :email_digest_items, :organization_id
+    add_index :email_digest_items, :user_id
+
+    # Indexes for email_digest_preferences
+    add_index :email_digest_preferences, [:user_id, :digest_type, :organization_id], 
+              unique: true,
+              name: 'index_digest_preferences_on_user_digest_org_unique'
+    add_index :email_digest_preferences, [:organization_id, :next_send_at], 
+              name: 'index_digest_preferences_on_org_next_send'
+    add_index :email_digest_preferences, [:organization_id, :enabled], 
+              name: 'index_digest_preferences_on_org_enabled'
+    add_index :email_digest_preferences, :user_id
+    add_index :email_digest_preferences, :organization_id
+
+    # Add check constraints
+    add_check_constraint :email_digest_preferences, 
+                         "frequency IN ('daily', 'weekly', 'custom')", 
+                         name: 'check_digest_preferences_frequency'
+    add_check_constraint :email_digest_preferences, 
+                         "time ~ '^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$'", 
+                         name: 'check_digest_preferences_time_format'
+    add_check_constraint :email_digest_preferences, 
+                         "day_of_week IS NULL OR (day_of_week >= 0 AND day_of_week <= 6)", 
+                         name: 'check_digest_preferences_day_of_week'
+  end
+end

data/lib/email_digest/generators/email_digest/install/templates/email_digest.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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
+  # Example:
+  # 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

data/lib/email_digest/models/digest_item.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  module Models
+    class DigestItem < ActiveRecord::Base
+      self.table_name = 'email_digest_items'
+
+      # Associations
+      # Note: User and Organization are in MongoDB, so we use string IDs
+      # belongs_to :user would require the User model to be in PostgreSQL
+      # For now, we'll keep it as a string reference
+
+      # Validations
+      validates :user_id, presence: true
+      validates :organization_id, presence: true
+      validates :digest_type, presence: true
+      validates :notification_type, presence: true
+
+      # Scopes
+      scope :pending, -> { where(processed: false) }
+      scope :for_user, ->(user) { where(user_id: user.id.to_s) }
+      scope :for_type, ->(type) { where(digest_type: type.to_s) }
+      scope :recent, -> { order(created_at: :desc) }
+      scope :for_organization, ->(org) { where(organization_id: org.id.to_s) }
+
+      # Class methods
+      def self.create_for_user(user, digest_type, notification_type, options = {})
+        organization = options[:organization] || user.organization
+        create(
+          user_id: user.id.to_s,
+          organization_id: organization.id.to_s,
+          digest_type: digest_type.to_s,
+          notification_type: notification_type.to_s,
+          subject: options[:subject],
+          body: options[:body],
+          metadata: options[:metadata] || {},
+          source_id: options[:source_id],
+          source_type: options[:source_type],
+          priority: options[:priority] || 0
+        )
+      end
+
+      # Instance methods
+      def mark_processed
+        update(processed: true, processed_at: Time.current)
+      end
+    end
+  end
+end

data/lib/email_digest/models/digest_preference.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  module Models
+    class DigestPreference < ActiveRecord::Base
+      self.table_name = 'email_digest_preferences'
+
+      # Validations
+      validates :user_id, presence: true
+      validates :organization_id, presence: true
+      validates :digest_type, presence: true
+      validates :frequency, inclusion: { in: %w[daily weekly custom] }
+      validates :time, format: { with: /\A([0-1]?[0-9]|2[0-3]):[0-5][0-9]\z/ }
+      validates :day_of_week, presence: true, if: -> { frequency == 'weekly' }
+      validates :timezone, inclusion: { in: ActiveSupport::TimeZone.all.map(&:name) }, allow_blank: true
+      validates :user_id, uniqueness: { scope: [:digest_type, :organization_id], 
+                                         message: 'already has a preference for this digest type in this organization' }
+
+      # Callbacks
+      before_save :calculate_next_send_at
+
+      # Scopes
+      scope :for_organization, ->(org) { where(organization_id: org.id.to_s) }
+      scope :enabled, -> { where(enabled: true) }
+
+      # Class methods
+      def self.for_user_and_type(user, digest_type, organization)
+        find_or_create_by(
+          user_id: user.id.to_s,
+          digest_type: digest_type.to_s,
+          organization_id: organization.id.to_s
+        ) do |pref|
+          pref.frequency = EmailDigest.configuration.default_frequency.to_s
+          pref.time = EmailDigest.configuration.default_time
+          pref.timezone = EmailDigest.configuration.default_timezone
+        end
+      end
+
+      def self.ready_to_send(organization = nil)
+        now = Time.current
+        query = where(enabled: true).where('next_send_at <= ?', now)
+        query = query.where(organization_id: organization.id.to_s) if organization
+        query
+      end
+
+      # Instance methods
+      def calculate_next_send_at
+        return unless enabled
+
+        time_parts = time.split(':')
+        hour = time_parts[0].to_i
+        minute = time_parts[1].to_i
+
+        # Safely handle timezone, fallback to UTC if invalid
+        begin
+          base_time = Time.current.in_time_zone(timezone)
+        rescue ArgumentError, TZInfo::InvalidTimezoneIdentifier
+          base_time = Time.current.in_time_zone('UTC')
+        end
+        target_time = base_time.change(hour: hour, min: minute, sec: 0)
+
+        case frequency
+        when 'daily'
+          self.next_send_at = target_time < base_time ? target_time + 1.day : target_time
+        when 'weekly'
+          days_until_target = (day_of_week - base_time.wday) % 7
+          days_until_target = 7 if days_until_target == 0 && target_time < base_time
+          self.next_send_at = (base_time.beginning_of_week + days_until_target.days).change(hour: hour, min: minute)
+        when 'custom'
+          calculate_custom_schedule
+        end
+      end
+
+      def calculate_custom_schedule
+        return unless custom_schedule.present?
+
+        # Custom schedule can be: { days: [1,3,5], time: "14:00" }
+        # Or cron-like: { cron: "0 9 * * 1,3,5" }
+        # For now, simple implementation
+        if custom_schedule['days'].present?
+          begin
+            base_time = Time.current.in_time_zone(timezone)
+          rescue ArgumentError, TZInfo::InvalidTimezoneIdentifier
+            base_time = Time.current.in_time_zone('UTC')
+          end
+          time_parts = (custom_schedule['time'] || time).split(':')
+          hour = time_parts[0].to_i
+          minute = time_parts[1].to_i
+
+          target_days = custom_schedule['days'].map(&:to_i)
+          current_day = base_time.wday
+          next_day = target_days.find { |d| d > current_day } || target_days.first
+          days_ahead = next_day > current_day ? next_day - current_day : (7 - current_day) + next_day
+
+          self.next_send_at = (base_time + days_ahead.days).change(hour: hour, min: minute)
+        end
+      end
+
+      def update_last_sent
+        self.last_sent_at = Time.current
+        calculate_next_send_at
+        save
+      end
+    end
+  end
+end

data/lib/email_digest/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  class Railtie < Rails::Railtie
+    generators do
+      require 'email_digest/generators/email_digest/install/install_generator'
+    end
+  end
+end

data/lib/email_digest/services/digest_collector.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EmailDigest
+  module Services
+    class DigestCollector
+      attr_reader :user, :digest_type, :organization
+
+      def initialize(user, digest_type, organization = nil)
+        @user = user
+        @digest_type = digest_type.to_sym
+        @organization = organization || user.organization
+      end
+
+      def collect_items(since: nil)
+        since ||= last_digest_sent_at || 7.days.ago
+
+        items = Models::DigestItem.pending
+                                  .for_user(user)
+                                  .for_type(digest_type)
+                                  .for_organization(organization)
+                                  .where('created_at >= ?', since)
+                                  .order(priority: :desc, created_at: :desc)
+                                  .limit(EmailDigest.configuration.max_items_per_digest)
+
+        items
+      end
+
+      def last_digest_sent_at
+        preference = Models::DigestPreference.find_by(
+          user_id: user.id.to_s,
+          digest_type: digest_type.to_s,
+          organization_id: organization.id.to_s
+        )
+        preference&.last_sent_at
+      end
+    end
+  end
+end