ses-dashboard 0.1.0

data/lib/ses_dashboard/stats_aggregator.rb

@@ -0,0 +1,107 @@
+module SesDashboard
+  # Aggregates email statistics for the dashboard.
+  #
+  # Usage:
+  #   agg = StatsAggregator.new(project_id: project.id, from: 14.days.ago, to: Time.current)
+  #   agg.counters       # => { sent: 100, delivered: 90, bounced: 3, ... }
+  #   agg.time_series    # => { labels: ["2024-01-01", ...], data: [5, 12, ...] }
+  #   agg.total_opens    # => 45
+  #   agg.total_clicks   # => 12
+  #
+  class StatsAggregator
+    def initialize(project_id: nil, from: nil, to: nil)
+      @project_id = project_id
+      @from       = from
+      @to         = to
+    end
+
+    # Returns counts grouped by status.
+    # "not_delivered" is derived as the sum of bounced + complained + rejected.
+    def counters
+      scope = base_scope
+      counts = scope.group(:status).count
+
+      not_delivered = (counts["bounced"] || 0) +
+                      (counts["complained"] || 0) +
+                      (counts["rejected"] || 0)
+
+      {
+        total:         scope.count,
+        sent:          counts["sent"] || 0,
+        delivered:     counts["delivered"] || 0,
+        bounced:       counts["bounced"] || 0,
+        complained:    counts["complained"] || 0,
+        rejected:      counts["rejected"] || 0,
+        failed:        counts["failed"] || 0,
+        not_delivered: not_delivered
+      }
+    end
+
+    def total_opens
+      base_scope.sum(:opens)
+    end
+
+    def total_clicks
+      base_scope.sum(:clicks)
+    end
+
+    # Returns a Chart.js-compatible hash: { labels: [...], data: [...] }
+    # Groups by calendar day over the from..to range, filling gaps with zero.
+    def time_series
+      from = effective_from
+      to   = effective_to
+
+      expr = Arel.sql(date_group_expr)
+      raw = base_scope
+              .where(sent_at: from..to)
+              .group(expr)
+              .order(expr)
+              .count
+
+      all_days = date_range_days(from, to)
+      labels   = all_days.map { |d| d.strftime("%Y-%m-%d") }
+      data     = all_days.map { |d| raw[d.strftime("%Y-%m-%d")] || 0 }
+
+      { labels: labels, data: data }
+    end
+
+    private
+
+    def base_scope
+      scope = SesDashboard::Email.all
+      scope = scope.where(project_id: @project_id) if @project_id
+      scope = scope.where(sent_at: @from..@to)     if @from && @to
+      scope
+    end
+
+    def date_group_expr
+      case connection.adapter_name.downcase
+      when "sqlite"
+        "strftime('%Y-%m-%d', sent_at)"
+      when "postgresql"
+        "TO_CHAR(sent_at AT TIME ZONE 'UTC', 'YYYY-MM-DD')"
+      else
+        # MySQL / MariaDB
+        "DATE_FORMAT(sent_at, '%Y-%m-%d')"
+      end
+    end
+
+    def connection
+      ActiveRecord::Base.connection
+    end
+
+    def effective_from
+      @from || 30.days.ago.beginning_of_day
+    end
+
+    def effective_to
+      @to || Time.current.end_of_day
+    end
+
+    def date_range_days(from, to)
+      from_d = from.to_date
+      to_d   = to.to_date
+      (from_d..to_d).to_a
+    end
+  end
+end

data/lib/ses_dashboard/version.rb

@@ -0,0 +1,3 @@
+module SesDashboard
+  VERSION = "0.1.0"
+end

data/lib/ses_dashboard/webhook_processor.rb

@@ -0,0 +1,116 @@
+require "json"
+require "net/http"
+require "uri"
+
+module SesDashboard
+  # Parses a raw SNS HTTP POST body and returns a normalized Result.
+  #
+  # Usage:
+  #   result = WebhookProcessor.new(request.body.read).process
+  #   case result.action
+  #   when :confirm_subscription
+  #     Net::HTTP.get(URI(result.subscribe_url))
+  #   when :process_event
+  #     WebhookEventPersistor.new(project, result).persist
+  #   end
+  #
+  class WebhookProcessor
+    Result = Struct.new(
+      :action,          # :confirm_subscription | :process_event | :unknown
+      :subscribe_url,   # present when action == :confirm_subscription
+      :event_type,      # "send" | "delivery" | "bounce" | "complaint" | "open" | "click" | "reject" | "rendering_failure"
+      :message_id,      # SES messageId
+      :destination,     # Array of recipient addresses
+      :source,          # From: address
+      :subject,         # Email subject (may be nil)
+      :occurred_at,     # Time
+      :raw_payload,     # The full parsed inner SES event Hash for storage
+      keyword_init: true
+    )
+
+    def initialize(raw_body)
+      @raw_body = raw_body
+    end
+
+    def process
+      sns = parse_json(@raw_body)
+      return unknown_result unless sns
+
+      case sns["Type"]
+      when "SubscriptionConfirmation"
+        Result.new(action: :confirm_subscription, subscribe_url: sns["SubscribeURL"])
+      when "Notification"
+        process_notification(sns)
+      else
+        unknown_result
+      end
+    rescue => e
+      Rails.logger.error("[SesDashboard] WebhookProcessor error: #{e.message}") if defined?(Rails)
+      unknown_result
+    end
+
+    private
+
+    def process_notification(sns)
+      message = parse_json(sns["Message"])
+      return unknown_result unless message
+
+      # SES supports two notification formats:
+      # - Event Publishing (newer): uses "eventType" key
+      # - Feedback Notifications (legacy): uses "notificationType" key
+      raw_event_type = (message["eventType"] || message["notificationType"] || "").downcase
+      event_type = normalize_event_type(raw_event_type)
+
+      mail      = message["mail"] || {}
+      timestamp = parse_time(mail["timestamp"] || sns["Timestamp"])
+
+      Result.new(
+        action:      :process_event,
+        event_type:  event_type,
+        message_id:  mail["messageId"],
+        destination: Array(mail["destination"]),
+        source:      mail["source"],
+        subject:     extract_subject(mail),
+        occurred_at: timestamp,
+        raw_payload: message
+      )
+    end
+
+    def normalize_event_type(raw)
+      case raw
+      when "send"              then "send"
+      when "delivery"          then "delivery"
+      when "bounce"            then "bounce"
+      when "complaint"         then "complaint"
+      when "open"              then "open"
+      when "click"             then "click"
+      when "reject"            then "reject"
+      when "renderingfailure"  then "rendering_failure"
+      else raw
+      end
+    end
+
+    def extract_subject(mail)
+      headers = Array(mail["headers"])
+      subj    = headers.find { |h| h["name"]&.casecmp("subject")&.zero? }
+      subj ? subj["value"] : (mail["commonHeaders"] || {})["subject"]
+    end
+
+    def parse_time(str)
+      return Time.now.utc unless str
+      Time.parse(str).utc
+    rescue ArgumentError
+      Time.now.utc
+    end
+
+    def parse_json(str)
+      JSON.parse(str)
+    rescue JSON::ParserError, TypeError
+      nil
+    end
+
+    def unknown_result
+      Result.new(action: :unknown)
+    end
+  end
+end

data/lib/ses_dashboard.rb

@@ -0,0 +1,66 @@
+require_relative "ses_dashboard/version"
+require_relative "ses_dashboard/client"
+require_relative "ses_dashboard/webhook_processor"
+require_relative "ses_dashboard/stats_aggregator"
+require_relative "ses_dashboard/paginatable"
+require_relative "ses_dashboard/auth/base"
+require_relative "ses_dashboard/auth/devise_adapter"
+require_relative "ses_dashboard/auth/cloudflare_adapter"
+
+module SesDashboard
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration) if block_given?
+  end
+
+  def self.reset_configuration!
+    self.configuration = Configuration.new
+  end
+
+  class Configuration
+    # AWS — credentials are optional. The SDK credential chain (SSO, IAM roles, instance
+    # profiles, env vars) is used when these are not explicitly set.
+    attr_accessor :aws_region, :aws_access_key_id, :aws_secret_access_key, :endpoint
+
+    # Auth — :none, :devise, :cloudflare, or any object responding to #authenticate(request)
+    attr_accessor :authentication_adapter
+
+    # Caching for SES API calls (quota, statistics, etc.)
+    attr_accessor :cache_enabled
+
+    # Dashboard behaviour
+    attr_accessor :per_page            # rows per page in activity log (default 25)
+    attr_accessor :time_zone           # time zone for chart grouping (default "UTC")
+    attr_accessor :test_email_from     # From: address used when sending test emails
+
+    # Security — set to true in production to validate SNS message signatures
+    attr_accessor :verify_sns_signature
+
+    # Cloudflare Zero Trust
+    attr_accessor :cloudflare_team_domain  # e.g. "myteam.cloudflareaccess.com"
+    attr_accessor :cloudflare_aud          # JWT audience (your CF application AUD)
+
+    def initialize
+      @aws_region              = ENV.fetch("AWS_REGION", "us-east-1")
+      @aws_access_key_id       = nil
+      @aws_secret_access_key   = nil
+      @endpoint                = ENV["AWS_ENDPOINT_URL"]  # LocalStack in dev/test
+      @authentication_adapter  = :none
+      @cache_enabled           = true
+      @per_page                = 25
+      @time_zone               = "UTC"
+      @test_email_from         = nil
+      @verify_sns_signature    = false
+      @cloudflare_team_domain  = nil
+      @cloudflare_aud          = nil
+    end
+  end
+
+  autoload :Engine, "ses_dashboard/engine"
+end

metadata

@@ -0,0 +1,369 @@
+--- !ruby/object:Gem::Specification
+name: ses-dashboard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- antodoms
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-ses
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails-controller-testing
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A mountable Rails engine that provides a real-time dashboard for Amazon
+  SES, tracking email delivery, bounces, complaints, opens, and clicks via SNS webhooks.
+email:
+- antodoms@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Dockerfile
+- README.md
+- Rakefile
+- app/assets/javascripts/ses_dashboard/application.js
+- app/assets/stylesheets/ses_dashboard/application.css
+- app/controllers/ses_dashboard/application_controller.rb
+- app/controllers/ses_dashboard/dashboard_controller.rb
+- app/controllers/ses_dashboard/emails_controller.rb
+- app/controllers/ses_dashboard/projects_controller.rb
+- app/controllers/ses_dashboard/test_emails_controller.rb
+- app/controllers/ses_dashboard/webhooks_controller.rb
+- app/helpers/ses_dashboard/application_helper.rb
+- app/models/ses_dashboard/application_record.rb
+- app/models/ses_dashboard/email.rb
+- app/models/ses_dashboard/email_event.rb
+- app/models/ses_dashboard/project.rb
+- app/services/ses_dashboard/webhook_event_persistor.rb
+- app/views/layouts/ses_dashboard/application.html.erb
+- app/views/ses_dashboard/dashboard/index.html.erb
+- app/views/ses_dashboard/emails/index.html.erb
+- app/views/ses_dashboard/emails/show.html.erb
+- app/views/ses_dashboard/projects/_form.html.erb
+- app/views/ses_dashboard/projects/edit.html.erb
+- app/views/ses_dashboard/projects/index.html.erb
+- app/views/ses_dashboard/projects/new.html.erb
+- app/views/ses_dashboard/projects/show.html.erb
+- app/views/ses_dashboard/shared/_flash.html.erb
+- app/views/ses_dashboard/shared/_pagination.html.erb
+- app/views/ses_dashboard/shared/_stat_card.html.erb
+- app/views/ses_dashboard/test_emails/new.html.erb
+- config/routes.rb
+- db/migrate/20240101000001_create_ses_dashboard_projects.rb
+- db/migrate/20240101000002_create_ses_dashboard_emails.rb
+- db/migrate/20240101000003_create_ses_dashboard_email_events.rb
+- docker-compose.yml
+- lib/ses_dashboard.rb
+- lib/ses_dashboard/auth/base.rb
+- lib/ses_dashboard/auth/cloudflare_adapter.rb
+- lib/ses_dashboard/auth/devise_adapter.rb
+- lib/ses_dashboard/client.rb
+- lib/ses_dashboard/engine.rb
+- lib/ses_dashboard/paginatable.rb
+- lib/ses_dashboard/stats_aggregator.rb
+- lib/ses_dashboard/version.rb
+- lib/ses_dashboard/webhook_processor.rb
+homepage: https://github.com/antodoms/ses_dashboard
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/antodoms/ses_dashboard
+  source_code_uri: https://github.com/antodoms/ses_dashboard
+  changelog_uri: https://github.com/antodoms/ses_dashboard/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: SES dashboard gem with pluggable authentication and AWS SES data fetching.
+test_files: []