sincerely 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3126012f05e46f992478bb05e997605aef323820d2fd72c95dfe3fa49105c33c
+  data.tar.gz: 5c5c1b66fc5e956506a634b8c4da25869019f741bb66e8517e28a08eef32c209
+SHA512:
+  metadata.gz: 0b093a942bbb2d4ae549e049e47595ca42e645211b1b6d1a92be1e035cac3aa3c690c1f829505bba4e0ae61fbbfa950e08f25a9bc1c4507be2a3e2f5a2555225
+  data.tar.gz: 4f75a74cd95ec7025a04c6d549591129f6736c9303f07f866fe4213f74ba72a2fe677fc699c668efc405271e09b5b0437679bcb61a19439450400f45323fd58c

data/.rspec

@@ -0,0 +1,3 @@
+--order random
+--profile 10
+--color

data/.rubocop.yml

@@ -0,0 +1,38 @@
+require:
+  - rubocop-rspec
+  - rubocop-rails
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+
+Style/Documentation:
+  Enabled: false
+Layout/LineLength:
+  Max: 120
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+# Controller methods can be complex; these metrics produce false positives
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+# Engines don't typically use i18n for simple flash messages
+Rails/I18nLocaleTexts:
+  Enabled: false
+
+# Keep :unprocessable_entity for Rails < 7.1 compatibility
+Rails/ResponseParsedBody:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2024-07-31
+
+### Added
+- Initial release
+- Amazon SES email sending
+- Amazon SES email sending events
+- liquid email templates
+- notification statuses

data/README.md

@@ -0,0 +1,202 @@
+# Sincerely
+## Introduction
+Sincerely is a versatile Ruby gem designed for creating, delivering and monitoring email, sms or push notifications.
+
+## Table of Contents
+1. [Installation](#installation)
+2. [Getting Started](#getting-started)
+3. [Configuration](#configuration)
+4. [Usage](#usage)
+5. [Notification model](#notification-model)
+6. [Notification states](#notification-states)
+7. [Callbacks](#callbacks)
+8. [How to Run Tests](#how-to-run-tests)
+9. [Guide for Contributing](#guide-for-contributing)
+10. [How to Contact Us](#how-to-contact-us)
+11. [License](#license)
+
+## Installation
+Sincerely 1.0 works with Rails 6.0 onwards. Run:
+```bash
+bundle add sincerely
+```
+
+## Getting Started
+
+1. First, you need to run the install generator, which will create the `config/sincerely.yml` initializer file for you:
+```bash
+rails g sincerely:install
+```
+
+2. You need to generate and run a migration to create the `notifications` and `notification_templates` tables and the `Notification` and the `NotificationTemplate` model:
+```bash
+rails g sincerely:migration Notification
+
+rails db:migrate
+```
+
+3. If you want to enable event callbacks you need to run the `events` task to create the `sincerely_delivery_events` and `sincerely_engagements_events` tables and the `Sincerely::DeliveryEvent` and `Sincerely::EngagementEvent` models:
+```bash
+rails g sincerely:events
+
+rails db:migrate
+```
+
+## Configuration
+1. You need to set the notification model generated in the previous step by setting the `notification_model_name` option in the `config/sincerely.yml` file:
+
+```
+# config/sincerely.yml
+defaults: &defaults
+  notification_model_name: Notification
+```
+
+2. You need to set the delivery system for each delivery methods (email/sms/push) by setting the `delivery_methods` option in the `config/sincerely.yml` file. Please note that right now the gem supports only AWS SES email notification (`Sincerely::DeliverySystems::EmailAwsSes` module).
+
+```
+# config/sincerely.yml
+defaults: &defaults
+  delivery_methods:
+    email:
+      delivery_system: Sincerely::DeliverySystems::EmailAwsSes
+      options:
+        region: region
+        access_key_id: your_access_key_id
+        secret_access_key: your_secret_access_key
+        configuration_set_name: config_set
+    sms:
+```
+
+* `region`: the AWS region to connect to
+* `access_key_id`: AWS access key id
+* `secret_access_key`: AWS secret access key
+* `configuration_set_name`: the name of the configuration set to use when sending the email, you don't need to specify the configuration set option if you don't want to handle SES email sending events
+
+Sincerely uses the `aws-sdk-sesv2` gem to send emails. See [sesv2](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/SESV2.html) for details.
+
+Furthermore you need to configure Amazon SES to be able to send emails, see [SES](https://docs.aws.amazon.com/ses/latest/dg/Welcome.html) for details.
+
+## Usage
+
+1. Once the email delivery method is configured you need to create an email template which is used to generate the email content:
+
+```
+Sincerely::Templates::EmailLiquidTemplate.create(
+  name: 'test',
+  subject: 'template for sending messages',
+  sender: 'john.doe@gmail.com'
+  html_content: 'hi {{name}}',
+  text_content: 'hi {{name}}'
+)
+```
+
+* `name`: unique id of the template
+* `subject`: subject of the generated email (can be overwritten in the notification)
+* `sender`: email address of the sender
+* `html_content`: html content of the generated email, you can use the liquid syntax to use variables in the content, see [liquid](https://github.com/Shopify/liquid) for details
+* `text_content`: text content of the generated email, you can use the liquid syntax to use variables in the content, see [liquid](https://github.com/Shopify/liquid) for details
+
+2. You need to create the notification:
+
+```
+Notification.create(
+  recipient: 'jane.doe@gmail.com',
+  notification_type: 'email',
+  template: Sincerely::Templates::EmailLiquidTemplate.first,
+  delivery_options: {
+    template_data: {
+      name: 'John Doe'
+    },
+    subject: 'subject'
+  }
+)
+```
+* `recipient`: recipient of the notification
+* `notification_type`: email/sms/push (please note that right now the gem supports only AWS SES email notifications)
+* `template`: template to generate the notification content
+* `delivery_options`: options for the associated template (`EmailLiquidTemplate` supports (i) the `template_data` option which contains the parameter hash for the liquid template defined in the html_content field of the associated template, (ii) the `subject` option which overwrites the subject defined in the associated template)
+
+
+3. You need to send the notification:
+
+```
+notification.deliver
+```
+
+## Notification model
+* `recipient`: recipient (email or phone number) of the notification
+* `notification_type`: email | sms | push
+* `delivery_options`: options for the associated template
+* `delivery_system`: associated delivery system
+* `delivery_state`: state of the notification
+* `template_id`: associated template
+* `sent_at`: timestamp of the delivery
+* `message_id`: message id generated by the delivery system
+* `error_message`: error message if the notification is rejected by the delivery system
+
+## Notification states
+* `draft`: default state, notification is not yet sent
+* `accepted`: the send request was successful and the delivery system will attempt to deliver the message to the recipient’s mail server
+* `rejected`: notification is rejected by the delivery system
+* `delivered`: notification is successfully delivered by the delivery system
+* `bounced`: notification is bounced (ie when an email cannot be delivered to the recipient)
+* `opened`: notification is opened
+* `clicked`: notification is clicked
+* `complained`: notification is complained (ie when the recipient of your email marks your email as spam)
+
+Please note that the notification state is updated only if the event callback is configured. 
+
+## Callbacks
+
+`EmailAwsSes` delivery system handles SES email sending events. To enable it make sure:
+* you have run the `events` task described in the `Getting Started` section
+* you have set the `configuration_set_name` option described in the `Configuration` section
+* you have run the following task that generates the webhook controller for you
+```bash
+rails g sincerely:aws_ses_webhook_controller SES_WEBHOOK
+```
+
+Furthermore you need to configure Amazon SES to monitor email sending, see [SES email sending events](https://docs.aws.amazon.com/ses/latest/dg/monitor-using-event-publishing.html) for details.
+
+Once the webhook controller is in place, it will:
+* update the state of the notifications
+* create event records for the bounce/complaint/open/click events
+
+Delivery events (delivery/bounce) fields:
+* `message_id`: message id generated by the delivery system
+* `delivery_system`: associated delivery system
+* `event_type`: delivery | bounce
+* `recipient`: recipient of the notification
+* `delivery_event_type`: bounce type
+* `delivery_event_subtype`: bounce subtype
+* `options`: other event specific options (if any)
+* `timestamp`: timestamp of the event
+
+Engagement events (open/click/compaint) fields:
+* `message_id`: message id generated by the delivery system
+* `delivery_system`: associated delivery system
+* `event_type`: open | click | compaint
+* `recipient`: recipient of the notification
+* `ip_address`: the recipient's IP address
+* `user_agent`: the user agent of the device or email client
+* `link`: the URL of the link that the recipient clicked
+* `feedback_type`: complaint feedback type
+* `options`: other event specific options (if any)
+* `timestamp`: timestamp of the event
+
+
+## How to Run Tests
+You can run unit tests for RubyBlok with the following command:
+```
+bundle exec rspec
+```
+
+## Guide for Contributing
+Contributions are made to this repository via Issues and Pull Requests (PRs).
+Issues should be used to report bugs, request a new feature, or to discuss potential changes before a PR is created.
+
+## How to Contact Us
+For any inquiries, reach out to us at: info@rubyblok.com
+
+## License
+RubyBlok is released under the MIT License.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/controllers/sincerely/application_controller.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Sincerely
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    layout 'sincerely/application'
+
+    before_action :authenticate_user!
+
+    helper_method :notification_model
+
+    private
+
+    def authenticate_user!
+      return unless Sincerely.authenticate_with
+
+      instance_exec(&Sincerely.authenticate_with)
+    end
+
+    def notification_model
+      @notification_model ||= Sincerely.notification_model
+    end
+
+    def paginate(collection, per_page: 25)
+      page = (params[:page] || 1).to_i
+      offset = (page - 1) * per_page
+      total = collection.count
+
+      {
+        records: collection.offset(offset).limit(per_page),
+        total_count: total,
+        current_page: page,
+        per_page:,
+        total_pages: (total.to_f / per_page).ceil
+      }
+    end
+
+    def time_filter_start
+      period = params[:period]
+      period = '24h' unless %w[1h 24h 7d 30d 3m all].include?(period)
+
+      case period
+      when '1h' then 1.hour.ago
+      when '24h' then 24.hours.ago
+      when '7d' then 7.days.ago
+      when '30d' then 30.days.ago
+      when '3m' then 3.months.ago
+      when 'all' then nil
+      end
+    end
+
+    def apply_time_filter(collection, column: :created_at)
+      start_time = time_filter_start
+      return collection unless start_time
+
+      collection.where("#{column} >= ?", start_time)
+    end
+
+    def apply_notification_filter(scope)
+      filter = Sincerely.config.filter_notifications_by
+      return scope unless filter.respond_to?(:call)
+
+      conditions = instance_exec(&filter)
+      return scope if conditions.blank?
+
+      scope.where(conditions)
+    end
+
+    def apply_event_filter(scope)
+      filter = Sincerely.config.filter_notifications_by
+      return scope unless filter.respond_to?(:call)
+
+      conditions = instance_exec(&filter)
+      return scope if conditions.blank?
+
+      message_ids = notification_model.where(conditions).where.not(message_id: nil).pluck(:message_id)
+      scope.where(message_id: message_ids)
+    end
+  end
+end

data/app/controllers/sincerely/dashboard_controller.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Sincerely
+  class DashboardController < ApplicationController
+    def index
+      filtered_notifications = apply_time_filter(notification_model)
+      filtered_notifications = apply_notification_filter(filtered_notifications)
+
+      @total_notifications = filtered_notifications.count
+      @notifications_by_state = filtered_notifications.group(:delivery_state).count
+      @recent_notifications = filtered_notifications.order(created_at: :desc).limit(10)
+
+      # Delivery rates
+      total_sent = filtered_notifications.where.not(delivery_state: %w[draft rejected]).count
+      delivered = filtered_notifications.where(delivery_state: %w[delivered opened clicked]).count
+      @delivery_rate = total_sent.positive? ? (delivered.to_f / total_sent * 100).round(1) : 0
+
+      # Engagement rates
+      delivered_count = filtered_notifications.where(delivery_state: %w[delivered opened clicked]).count
+      engaged = filtered_notifications.where(delivery_state: %w[opened clicked]).count
+      @open_rate = delivered_count.positive? ? (engaged.to_f / delivered_count * 100).round(1) : 0
+
+      # Recent events (filtered by user's notifications)
+      user_message_ids = filtered_notifications.where.not(message_id: nil).pluck(:message_id)
+      @recent_delivery_events = apply_time_filter(Sincerely::DeliveryEvent)
+                                .where(message_id: user_message_ids)
+                                .order(created_at: :desc).limit(5)
+      @recent_engagement_events = apply_time_filter(Sincerely::EngagementEvent)
+                                  .where(message_id: user_message_ids)
+                                  .order(created_at: :desc).limit(5)
+
+      # Bounce rate
+      bounced = filtered_notifications.where(delivery_state: 'bounced').count
+      @bounce_rate = total_sent.positive? ? (bounced.to_f / total_sent * 100).round(1) : 0
+
+      # Current period for display
+      @current_period = params[:period] || '24h'
+
+      @notifications_timeline = build_timeline_data(filtered_notifications)
+    end
+
+    private
+
+    def build_timeline_data(notifications)
+      bucket_config = timeline_bucket_config
+      buckets = generate_time_buckets(bucket_config)
+      interval = bucket_config[:interval]
+      series = {}
+
+      notifications.find_each do |notification|
+        bucket_index = find_bucket_index(notification.created_at, buckets, interval)
+        next if bucket_index.nil?
+
+        state = notification.delivery_state
+        series[state] ||= Array.new(buckets.length, 0)
+        series[state][bucket_index] += 1
+      end
+
+      labels = buckets.map { |b| format_bucket_label(b, bucket_config) }
+
+      { labels:, series:, buckets: }
+    end
+
+    def timeline_bucket_config
+      period = params[:period]
+      period = '24h' unless %w[1h 24h 7d 30d 3m all].include?(period)
+
+      case period
+      when '1h'
+        { interval: 5.minutes, format: '%H:%M', start: 1.hour.ago }
+      when '24h'
+        { interval: 1.hour, format: '%H:%M', start: 24.hours.ago }
+      when '7d'
+        { interval: 6.hours, format: '%a %H:%M', start: 7.days.ago }
+      when '30d'
+        { interval: 1.day, format: '%b %d', start: 30.days.ago }
+      when '3m'
+        { interval: 1.week, format: '%b %d', start: 3.months.ago }
+      when 'all'
+        { interval: 1.month, format: '%b %Y', start: 1.year.ago }
+      end
+    end
+
+    def generate_time_buckets(config)
+      buckets = []
+      current = config[:start].beginning_of_hour
+      now = Time.current
+
+      while current <= now
+        buckets << current
+        current += config[:interval]
+      end
+
+      buckets
+    end
+
+    def find_bucket_index(time, buckets, interval)
+      return nil if buckets.empty?
+
+      buckets.each_with_index do |bucket_start, index|
+        bucket_end = bucket_start + interval
+        return index if time >= bucket_start && time < bucket_end
+      end
+
+      buckets.length - 1 if time >= buckets.last && time < buckets.last + interval
+    end
+
+    def format_bucket_label(bucket, config)
+      bucket.strftime(config[:format])
+    end
+  end
+end

data/app/controllers/sincerely/delivery_events_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Sincerely
+  class DeliveryEventsController < ApplicationController
+    def index
+      @events = apply_time_filter(Sincerely::DeliveryEvent).order(created_at: :desc)
+      @events = apply_event_filter(@events)
+
+      @events = @events.where(event_type: params[:event_type]) if params[:event_type].present?
+      @events = @events.where('recipient LIKE ?', "%#{params[:recipient]}%") if params[:recipient].present?
+
+      if params[:template_id].present? || params[:notification_type].present?
+        notification_scope = notification_model.all
+        if params[:template_id].present?
+          notification_scope = notification_scope.where(template_id: params[:template_id])
+        end
+        if params[:notification_type].present?
+          notification_scope = notification_scope.where(notification_type: params[:notification_type])
+        end
+        message_ids = notification_scope.pluck(:message_id).compact
+        @events = @events.where(message_id: message_ids)
+      end
+
+      @pagination = paginate(@events)
+      @events = @pagination[:records]
+
+      @event_types = Sincerely::DeliveryEvent.distinct.pluck(:event_type).compact
+      @templates = Sincerely::Templates::NotificationTemplate.all
+    end
+  end
+end

data/app/controllers/sincerely/engagement_events_controller.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Sincerely
+  class EngagementEventsController < ApplicationController
+    def index
+      @events = apply_time_filter(Sincerely::EngagementEvent).order(created_at: :desc)
+      @events = apply_event_filter(@events)
+
+      @events = @events.where(event_type: params[:event_type]) if params[:event_type].present?
+      @events = @events.where('recipient LIKE ?', "%#{params[:recipient]}%") if params[:recipient].present?
+
+      # Filter by notification properties via message_id
+      if params[:template_id].present? || params[:notification_type].present?
+        notification_scope = notification_model.all
+        if params[:template_id].present?
+          notification_scope = notification_scope.where(template_id: params[:template_id])
+        end
+        if params[:notification_type].present?
+          notification_scope = notification_scope.where(notification_type: params[:notification_type])
+        end
+        message_ids = notification_scope.pluck(:message_id).compact
+        @events = @events.where(message_id: message_ids)
+      end
+
+      @pagination = paginate(@events)
+      @events = @pagination[:records]
+
+      @event_types = Sincerely::EngagementEvent.distinct.pluck(:event_type).compact
+      @templates = Sincerely::Templates::NotificationTemplate.all
+    end
+  end
+end

data/app/controllers/sincerely/notifications_controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Sincerely
+  class NotificationsController < ApplicationController
+    def index
+      @notifications = apply_time_filter(notification_model).order(created_at: :desc)
+
+      # Apply host app filter (e.g., filter by logged-in user's email)
+      @notifications = apply_notification_filter(@notifications)
+
+      # Apply filters
+      @notifications = @notifications.where(delivery_state: params[:status]) if params[:status].present?
+      @notifications = @notifications.where(template_id: params[:template_id]) if params[:template_id].present?
+      if params[:recipient].present?
+        @notifications = @notifications.where('recipient LIKE ?',
+                                              "%#{params[:recipient]}%")
+      end
+      if params[:notification_type].present?
+        @notifications = @notifications.where(notification_type: params[:notification_type])
+      end
+
+      @notifications = @notifications.where(created_at: Date.parse(params[:date_from])..) if params[:date_from].present?
+      if params[:date_to].present?
+        @notifications = @notifications.where(created_at: ..Date.parse(params[:date_to]).end_of_day)
+      end
+
+      @pagination = paginate(@notifications)
+      @notifications = @pagination[:records]
+      @templates = Sincerely::Templates::NotificationTemplate.all
+      @states = notification_model.aasm.states.map(&:name)
+    end
+
+    def show
+      @notification = apply_notification_filter(notification_model).find(params[:id])
+      @template = @notification.template
+      @timeline = build_event_timeline(@notification)
+    end
+
+    private
+
+    def build_event_timeline(notification)
+      events = []
+
+      Sincerely::DeliveryEvent.where(message_id: notification.message_id).find_each do |event|
+        events << {
+          type: event.event_type,
+          timestamp: event.timestamp || event.created_at,
+          details: format_event_details(event.options)
+        }
+      end
+
+      Sincerely::EngagementEvent.where(message_id: notification.message_id).find_each do |event|
+        events << {
+          type: event.event_type,
+          timestamp: event.timestamp || event.created_at,
+          details: format_event_details(event.options)
+        }
+      end
+
+      events.sort_by { |e| e[:timestamp] }.reverse
+    end
+
+    def format_event_details(data)
+      return nil if data.blank?
+
+      data.is_a?(Hash) ? data.map { |k, v| "#{k}: #{v}" }.join(', ') : data.to_s
+    end
+  end
+end