ses-dashboard 0.1.0

data/app/controllers/ses_dashboard/emails_controller.rb

@@ -0,0 +1,93 @@
+require "csv"
+
+module SesDashboard
+  class EmailsController < ApplicationController
+    before_action :set_project
+
+    def index
+      scope = filtered_scope
+      @emails, @pagination = Paginatable.paginate(scope, page: params[:page])
+
+      respond_to do |format|
+        format.html
+        format.json { render json: serialize_emails(@emails) }
+      end
+    end
+
+    def show
+      @email  = @project.emails.find(params[:id])
+      @events = @email.email_events.ordered
+    end
+
+    def export
+      scope = filtered_scope
+
+      respond_to do |format|
+        format.csv do
+          send_data generate_csv(scope), filename: "emails-#{Date.today}.csv", type: "text/csv"
+        end
+        format.json do
+          send_data serialize_emails(scope).to_json,
+                    filename: "emails-#{Date.today}.json",
+                    type: "application/json"
+        end
+      end
+    end
+
+    private
+
+    def set_project
+      @project = Project.find(params[:project_id])
+    end
+
+    def filtered_scope
+      scope = @project.emails.ordered
+      scope = scope.search(params[:q])
+      scope = scope.by_status(params[:status])
+      scope = scope.in_date_range(
+        parse_date(params[:from_date]),
+        parse_date(params[:to_date])
+      )
+      scope
+    end
+
+    def parse_date(str)
+      Time.zone.parse(str) if str.present?
+    rescue ArgumentError
+      nil
+    end
+
+    def generate_csv(scope)
+      CSV.generate(headers: true) do |csv|
+        csv << %w[message_id source subject destination status opens clicks sent_at]
+        scope.each do |email|
+          csv << [
+            email.message_id,
+            email.source,
+            email.subject,
+            Array(email.destination).join("; "),
+            email.status,
+            email.opens,
+            email.clicks,
+            email.sent_at&.iso8601
+          ]
+        end
+      end
+    end
+
+    def serialize_emails(emails)
+      emails.map do |e|
+        {
+          message_id:  e.message_id,
+          source:      e.source,
+          subject:     e.subject,
+          destination: e.destination,
+          status:      e.status,
+          opens:       e.opens,
+          clicks:      e.clicks,
+          sent_at:     e.sent_at&.iso8601
+        }
+      end
+    end
+  end
+end

data/app/controllers/ses_dashboard/projects_controller.rb

@@ -0,0 +1,67 @@
+module SesDashboard
+  class ProjectsController < ApplicationController
+    before_action :set_project, only: [:show, :edit, :update, :destroy]
+
+    def index
+      @projects = Project.ordered
+    end
+
+    def show
+      from = parse_date(params[:from]) || 30.days.ago.beginning_of_day
+      to   = parse_date(params[:to])   || Time.current.end_of_day
+
+      agg = StatsAggregator.new(project_id: @project.id, from: from, to: to)
+
+      @counters     = agg.counters
+      @total_opens  = agg.total_opens
+      @total_clicks = agg.total_clicks
+      @chart_data   = agg.time_series
+      @from         = from
+      @to           = to
+    end
+
+    def new
+      @project = Project.new
+    end
+
+    def create
+      @project = Project.new(project_params)
+      if @project.save
+        redirect_to project_path(@project), notice: "Project created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def edit; end
+
+    def update
+      if @project.update(project_params)
+        redirect_to project_path(@project), notice: "Project updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @project.destroy
+      redirect_to projects_path, notice: "Project deleted."
+    end
+
+    private
+
+    def set_project
+      @project = Project.find(params[:id])
+    end
+
+    def project_params
+      params.require(:project).permit(:name, :description)
+    end
+
+    def parse_date(str)
+      Time.zone.parse(str) if str.present?
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/controllers/ses_dashboard/test_emails_controller.rb

@@ -0,0 +1,38 @@
+module SesDashboard
+  class TestEmailsController < ApplicationController
+    before_action :set_project
+
+    def new
+      @from = SesDashboard.configuration.test_email_from
+    end
+
+    def create
+      from    = params[:from].presence || SesDashboard.configuration.test_email_from
+      to      = params[:to].presence
+      subject = params[:subject].presence || "Test email from SES Dashboard"
+      body    = params[:body].presence || "This is a test email sent via the SES Dashboard."
+
+      unless from && to
+        flash.now[:alert] = "From and To addresses are required."
+        @from = from
+        return render :new, status: :unprocessable_entity
+      end
+
+      begin
+        ses_client = SesDashboard::Client.new
+        ses_client.send_email(from: from, to: to, subject: subject, body: body)
+        redirect_to project_path(@project), notice: "Test email sent to #{to}."
+      rescue => e
+        flash.now[:alert] = "Failed to send email: #{e.message}"
+        @from = from
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def set_project
+      @project = Project.find(params[:project_id])
+    end
+  end
+end

data/app/controllers/ses_dashboard/webhooks_controller.rb

@@ -0,0 +1,39 @@
+require "net/http"
+require "uri"
+
+module SesDashboard
+  class WebhooksController < ApplicationController
+    # Webhooks are authenticated by the project token in the URL, not by session auth.
+    skip_before_action :authenticate!
+    skip_before_action :verify_authenticity_token
+
+    def create
+      project = Project.find_by!(token: params[:project_token])
+      body    = request.body.read
+
+      result = WebhookProcessor.new(body).process
+
+      case result.action
+      when :confirm_subscription
+        confirm_subscription(result.subscribe_url)
+      when :process_event
+        WebhookEventPersistor.new(project, result).persist
+      end
+
+      head :ok
+    rescue ActiveRecord::RecordNotFound
+      head :not_found
+    rescue => e
+      Rails.logger.error("[SesDashboard] Webhook error: #{e.message}") if defined?(Rails)
+      head :unprocessable_entity
+    end
+
+    private
+
+    def confirm_subscription(url)
+      Net::HTTP.get(URI(url))
+    rescue => e
+      Rails.logger.warn("[SesDashboard] SNS subscription confirm failed: #{e.message}") if defined?(Rails)
+    end
+  end
+end

data/app/helpers/ses_dashboard/application_helper.rb

@@ -0,0 +1,47 @@
+module SesDashboard
+  module ApplicationHelper
+    STATUS_BADGE_CLASSES = {
+      "sent"       => "badge-sent",
+      "delivered"  => "badge-delivered",
+      "bounced"    => "badge-bounced",
+      "complained" => "badge-complained",
+      "rejected"   => "badge-rejected",
+      "failed"     => "badge-failed"
+    }.freeze
+
+    def status_badge(status)
+      css = STATUS_BADGE_CLASSES.fetch(status.to_s, "badge-unknown")
+      content_tag(:span, status.to_s.capitalize, class: "badge #{css}")
+    end
+
+    def format_event_type(type)
+      type.to_s.gsub("_", " ").capitalize
+    end
+
+    def webhook_url_for(project)
+      ses_dashboard.webhook_url(project.token)
+    end
+
+    def format_destination(destination)
+      Array(destination).join(", ")
+    end
+
+    def chart_data_tag(data)
+      content_tag(:script, data.to_json.html_safe,
+                  id: "chart-data", type: "application/json")
+    end
+
+    def date_range_link(label, days)
+      from = days.days.ago.beginning_of_day
+      to   = Time.current.end_of_day
+      link_to label, request.path + "?from=#{from.iso8601}&to=#{to.iso8601}",
+              class: "date-preset-link"
+    end
+
+    def pagination_link(label, page, params_override = {})
+      return content_tag(:span, label, class: "pagination-disabled") unless page
+      link_to label, request.path + "?" + request.query_parameters.merge(params_override.merge(page: page)).to_query,
+              class: "pagination-link"
+    end
+  end
+end

data/app/models/ses_dashboard/application_record.rb

@@ -0,0 +1,5 @@
+module SesDashboard
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/ses_dashboard/email.rb

@@ -0,0 +1,48 @@
+module SesDashboard
+  class Email < ApplicationRecord
+    self.table_name = "ses_dashboard_emails"
+
+    belongs_to :project, class_name: "SesDashboard::Project"
+    has_many   :email_events, class_name: "SesDashboard::EmailEvent", dependent: :destroy
+
+    # destination is a JSON-encoded array of recipient addresses
+    serialize :destination, coder: JSON
+
+    STATUSES = %w[sent delivered bounced complained rejected failed].freeze
+
+    validates :message_id,  presence: true, uniqueness: true
+    validates :source,      presence: true
+    validates :destination, presence: true
+    validates :status,      inclusion: { in: STATUSES }
+
+    scope :by_project,    ->(project_id) { where(project_id: project_id) }
+    scope :in_date_range, ->(from, to)   { where(sent_at: from..to) if from && to }
+    scope :by_status,     ->(status)     { where(status: status) if status.present? }
+    scope :ordered,       -> { order(sent_at: :desc, created_at: :desc) }
+
+    scope :search, ->(query) {
+      return all unless query.present?
+      term = "%#{sanitize_sql_like(query)}%"
+      where("source LIKE :q OR subject LIKE :q OR destination LIKE :q", q: term)
+    }
+
+    # State-machine transitions applied when SNS events arrive.
+    # Only advance; never move backward (e.g., a late delivery event doesn't
+    # overwrite a bounce).
+    TRANSITIONS = {
+      "sent"       => %w[delivered bounced complained rejected failed],
+      "delivered"  => %w[complained],
+      "bounced"    => [],
+      "complained" => [],
+      "rejected"   => [],
+      "failed"     => []
+    }.freeze
+
+    def apply_status!(new_status)
+      return if status == new_status
+      return unless TRANSITIONS.fetch(status, []).include?(new_status)
+
+      update_column(:status, new_status)
+    end
+  end
+end

data/app/models/ses_dashboard/email_event.rb

@@ -0,0 +1,18 @@
+module SesDashboard
+  class EmailEvent < ApplicationRecord
+    self.table_name = "ses_dashboard_email_events"
+
+    belongs_to :email, class_name: "SesDashboard::Email"
+
+    serialize :event_data, coder: JSON
+
+    EVENT_TYPES = %w[
+      send delivery bounce complaint open click reject rendering_failure
+    ].freeze
+
+    validates :event_type,  inclusion: { in: EVENT_TYPES }
+    validates :occurred_at, presence: true
+
+    scope :ordered, -> { order(occurred_at: :asc) }
+  end
+end

data/app/models/ses_dashboard/project.rb

@@ -0,0 +1,20 @@
+module SesDashboard
+  class Project < ApplicationRecord
+    self.table_name = "ses_dashboard_projects"
+
+    has_many :emails, class_name: "SesDashboard::Email", dependent: :destroy
+
+    validates :name,  presence: true
+    validates :token, presence: true, uniqueness: true
+
+    before_validation :generate_token, on: :create
+
+    scope :ordered, -> { order(:name) }
+
+    private
+
+    def generate_token
+      self.token ||= SecureRandom.hex(16)
+    end
+  end
+end

data/app/services/ses_dashboard/webhook_event_persistor.rb

@@ -0,0 +1,69 @@
+module SesDashboard
+  # Persists a processed SNS event (from WebhookProcessor::Result) to the database.
+  #
+  # Separating parsing (WebhookProcessor, in lib/) from persistence (here) keeps
+  # the parser free of Rails/AR dependencies and fully unit-testable.
+  #
+  class WebhookEventPersistor
+    def initialize(project, result)
+      @project = project
+      @result  = result
+    end
+
+    def persist
+      return if @result.message_id.blank?
+
+      ActiveRecord::Base.transaction do
+        email = find_or_create_email
+        create_event(email)
+        update_email_state(email)
+      end
+    rescue ActiveRecord::RecordInvalid => e
+      log_error("Failed to persist webhook event: #{e.message}")
+    end
+
+    private
+
+    def find_or_create_email
+      Email.find_or_initialize_by(message_id: @result.message_id) do |e|
+        e.project     = @project
+        e.destination = @result.destination
+        e.source      = @result.source
+        e.subject     = @result.subject
+        e.sent_at     = @result.occurred_at
+        e.status      = "sent"
+      end.tap(&:save!)
+    end
+
+    def create_event(email)
+      email.email_events.create!(
+        event_type:  @result.event_type,
+        event_data:  @result.raw_payload,
+        occurred_at: @result.occurred_at
+      )
+    end
+
+    def update_email_state(email)
+      case @result.event_type
+      when "delivery"
+        email.apply_status!("delivered")
+      when "bounce"
+        email.apply_status!("bounced")
+      when "complaint"
+        email.apply_status!("complained")
+      when "reject"
+        email.apply_status!("rejected")
+      when "rendering_failure"
+        email.apply_status!("failed")
+      when "open"
+        Email.update_counters(email.id, opens: 1)
+      when "click"
+        Email.update_counters(email.id, clicks: 1)
+      end
+    end
+
+    def log_error(msg)
+      defined?(Rails) ? Rails.logger.error("[SesDashboard] #{msg}") : nil
+    end
+  end
+end

data/app/views/layouts/ses_dashboard/application.html.erb

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>SES Dashboard</title>
+  <%= stylesheet_link_tag "ses_dashboard/application", media: "all" %>
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4" defer></script>
+  <%= javascript_include_tag "ses_dashboard/application", defer: true %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+  <nav class="ses-nav">
+    <span class="ses-nav-brand">SES Dashboard</span>
+    <%= link_to "Dashboard", root_path %>
+    <%= link_to "Projects",  projects_path %>
+    <span class="ses-nav-spacer"></span>
+  </nav>
+
+  <div class="ses-container">
+    <%= render "ses_dashboard/shared/flash" %>
+    <%= yield %>
+  </div>
+</body>
+</html>

data/app/views/ses_dashboard/dashboard/index.html.erb

@@ -0,0 +1,56 @@
+<div class="page-header">
+  <h1 class="page-title">Dashboard</h1>
+  <form method="get" style="display:flex;gap:.5rem;align-items:center;">
+    <input type="date" name="from" class="form-control" value="<%= @from.to_date %>" style="width:auto;">
+    <span>to</span>
+    <input type="date" name="to"   class="form-control" value="<%= @to.to_date   %>" style="width:auto;">
+    <button type="submit" class="btn btn-outline btn-sm">Apply</button>
+  </form>
+</div>
+
+<div class="stat-grid">
+  <%= render "ses_dashboard/shared/stat_card", label: "Sent",          value: @counters[:total],         color: "var(--color-text)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Delivered",     value: @counters[:delivered],     color: "var(--color-delivered)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Opens",         value: @total_opens,              color: "var(--color-primary)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Clicks",        value: @total_clicks,             color: "var(--color-primary)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Not Delivered", value: @counters[:not_delivered], color: "var(--color-bounced)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Bounced",       value: @counters[:bounced],       color: "var(--color-bounced)" %>
+  <%= render "ses_dashboard/shared/stat_card", label: "Complained",    value: @counters[:complained],    color: "var(--color-complained)" %>
+</div>
+
+<div class="card chart-card">
+  <div class="card-title">Email volume (by day)</div>
+  <canvas id="activity-chart"></canvas>
+</div>
+<%= chart_data_tag(@chart_data) %>
+
+<div class="page-header" style="margin-top:1.5rem;">
+  <h2 class="page-title" style="font-size:1rem;">Projects</h2>
+  <%= link_to "Manage projects", projects_path, class: "btn btn-outline btn-sm" %>
+</div>
+
+<div class="table-wrapper">
+  <table>
+    <thead>
+      <tr>
+        <th>Project</th>
+        <th>Total emails</th>
+        <th>Activity</th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @projects.each do |project| %>
+        <tr>
+          <td><%= link_to project.name, project_path(project) %></td>
+          <td><%= number_with_delimiter(project.emails.count) %></td>
+          <td><%= link_to "View activity", project_emails_path(project) %></td>
+        </tr>
+      <% end %>
+      <% if @projects.empty? %>
+        <tr><td colspan="3" style="color:var(--color-text-muted);text-align:center;padding:2rem;">
+          No projects yet. <%= link_to "Create one", new_project_path %>.
+        </td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/ses_dashboard/emails/index.html.erb

@@ -0,0 +1,72 @@
+<div class="page-header">
+  <h1 class="page-title">Activity — <%= @project.name %></h1>
+  <div style="display:flex;gap:.5rem;">
+    <%= link_to "Export CSV",  export_project_emails_path(@project, request.query_parameters.merge(format: :csv)),  class: "btn btn-outline btn-sm" %>
+    <%= link_to "Export JSON", export_project_emails_path(@project, request.query_parameters.merge(format: :json)), class: "btn btn-outline btn-sm" %>
+  </div>
+</div>
+
+<%= form_with url: project_emails_path(@project), method: :get, local: true do |f| %>
+  <div class="filter-bar">
+    <div class="form-group">
+      <label class="form-label" for="q">Search</label>
+      <input type="text" name="q" id="q" class="form-control" value="<%= params[:q] %>" placeholder="Subject, from, to&hellip;">
+    </div>
+    <div class="form-group">
+      <label class="form-label">Status</label>
+      <select name="status" class="form-control">
+        <option value="">All</option>
+        <% SesDashboard::Email::STATUSES.each do |s| %>
+          <option value="<%= s %>" <%= "selected" if params[:status] == s %>><%= s.capitalize %></option>
+        <% end %>
+      </select>
+    </div>
+    <div class="form-group">
+      <label class="form-label">From date</label>
+      <input type="date" name="from_date" class="form-control" value="<%= params[:from_date] %>">
+    </div>
+    <div class="form-group">
+      <label class="form-label">To date</label>
+      <input type="date" name="to_date" class="form-control" value="<%= params[:to_date] %>">
+    </div>
+    <div class="form-group" style="align-self:flex-end;">
+      <button type="submit" class="btn btn-primary btn-sm">Filter</button>
+      <%= link_to "Reset", project_emails_path(@project), class: "btn btn-outline btn-sm", id: "filter-reset" %>
+    </div>
+  </div>
+<% end %>
+
+<div class="table-wrapper">
+  <table>
+    <thead>
+      <tr>
+        <th>Subject</th>
+        <th>From</th>
+        <th>To</th>
+        <th>Status</th>
+        <th>Sent at</th>
+        <th>Opens</th>
+        <th>Clicks</th>
+        <th></th>
+      </tr>
+    </thead>
+    <tbody>
+      <% @emails.each do |email| %>
+        <tr>
+          <td><%= email.subject.presence || "(no subject)" %></td>
+          <td><%= email.source %></td>
+          <td><%= format_destination(email.destination) %></td>
+          <td><%= status_badge(email.status) %></td>
+          <td style="white-space:nowrap;"><%= email.sent_at&.strftime("%Y-%m-%d %H:%M") || "—" %></td>
+          <td><%= email.opens %></td>
+          <td><%= email.clicks %></td>
+          <td><%= link_to "Details", project_email_path(@project, email), class: "btn btn-sm btn-outline" %></td>
+        </tr>
+      <% end %>
+      <% if @emails.empty? %>
+        <tr><td colspan="8" style="color:var(--color-text-muted);text-align:center;padding:2rem;">No emails found.</td></tr>
+      <% end %>
+    </tbody>
+  </table>
+  <%= render "ses_dashboard/shared/pagination", pagination: @pagination %>
+</div>

data/app/views/ses_dashboard/emails/show.html.erb

@@ -0,0 +1,60 @@
+<div class="page-header">
+  <h1 class="page-title">Email detail</h1>
+  <%= link_to "&larr; Back to activity".html_safe, project_emails_path(@project), class: "btn btn-outline btn-sm" %>
+</div>
+
+<div class="card" style="margin-bottom:1.5rem;">
+  <table style="width:100%;border:none;">
+    <tbody>
+      <tr>
+        <td style="width:120px;color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">Subject</td>
+        <td><%= @email.subject.presence || "(no subject)" %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">From</td>
+        <td><%= @email.source %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">To</td>
+        <td><%= format_destination(@email.destination) %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">Status</td>
+        <td><%= status_badge(@email.status) %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">Sent at</td>
+        <td><%= @email.sent_at&.strftime("%Y-%m-%d %H:%M UTC") || "—" %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">Opens / Clicks</td>
+        <td><%= @email.opens %> / <%= @email.clicks %></td>
+      </tr>
+      <tr>
+        <td style="color:var(--color-text-muted);font-weight:600;padding:.4rem 0;">Message ID</td>
+        <td style="font-family:monospace;font-size:.8125rem;"><%= @email.message_id %></td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+<h2 class="page-title" style="font-size:1rem;margin-bottom:1rem;">Event timeline</h2>
+
+<ul class="event-timeline card">
+  <% @events.each do |event| %>
+    <li class="event-item">
+      <span class="event-time"><%= event.occurred_at&.strftime("%Y-%m-%d %H:%M:%S UTC") %></span>
+      <div>
+        <%= status_badge(event.event_type) %>
+        <% if event.event_data.present? %>
+          <br>
+          <button class="event-data-toggle">Show raw</button>
+          <pre class="event-raw"><%= JSON.pretty_generate(event.event_data) %></pre>
+        <% end %>
+      </div>
+    </li>
+  <% end %>
+  <% if @events.empty? %>
+    <li style="padding:1rem;color:var(--color-text-muted);">No events recorded.</li>
+  <% end %>
+</ul>