consentful 0.1.0.pre1

data/app/javascript/consentful/state.js

@@ -0,0 +1,91 @@
+import Cookies from 'js-cookie';
+
+// Cookie name is configurable so it matches the host's Consentful.config.cookie_name.
+// Call configureConsent({ cookieName }) once at boot (registerConsentful does this).
+let cookieName = 'consent';
+const EXPIRY_MONTHS = 12;
+const EMPTY_STATE = Object.freeze({
+  version_id: null,
+  categories: {},
+  services: {},
+  recorded_at: null,
+});
+
+export function configureConsent({ cookieName: name } = {}) {
+  if (name) cookieName = name;
+}
+
+export function readConsent() {
+  const raw = Cookies.get(cookieName);
+  if (!raw) return { ...EMPTY_STATE };
+
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      version_id: parsed.version_id ?? null,
+      categories: parsed.categories ?? {},
+      services: parsed.services ?? {},
+      recorded_at: parsed.recorded_at ?? null,
+    };
+  } catch (_err) {
+    return { ...EMPTY_STATE };
+  }
+}
+
+export function isExpired(state) {
+  if (!state.recorded_at) return true;
+  const recordedMs = state.recorded_at * 1000;
+  const expiryMs = EXPIRY_MONTHS * 30 * 24 * 60 * 60 * 1000;
+  return Date.now() - recordedMs > expiryMs;
+}
+
+export function matchesVersion(state, expectedVersionId) {
+  if (!expectedVersionId || !state.version_id) return false;
+  return Number(state.version_id) === Number(expectedVersionId);
+}
+
+export function shouldShowBanner(state, expectedVersionId) {
+  if (!state.recorded_at) return true;
+  if (isExpired(state)) return true;
+  if (!matchesVersion(state, expectedVersionId)) return true;
+  return false;
+}
+
+export function isServiceAllowed(state, { slug, categoryKey, categoryRequired }) {
+  if (categoryRequired) return true;
+  if (Object.prototype.hasOwnProperty.call(state.services, slug)) {
+    return Boolean(state.services[slug]);
+  }
+  return Boolean(state.categories[categoryKey]);
+}
+
+export function applyConsent(state, categoryGtagKeys = {}) {
+  if (typeof window === 'undefined') return;
+
+  window.dataLayer = window.dataLayer || [];
+  window.dataLayer.push({
+    event: 'consent_update',
+    consent: {
+      version_id: state.version_id,
+      categories: state.categories,
+      services: state.services,
+    },
+  });
+
+  if (typeof window.gtag === 'function' && Object.keys(categoryGtagKeys).length > 0) {
+    const update = {};
+    for (const [categoryKey, signals] of Object.entries(categoryGtagKeys)) {
+      const allowed = state.categories[categoryKey] ? 'granted' : 'denied';
+      for (const signal of signals) update[signal] = allowed;
+    }
+    window.gtag('consent', 'update', update);
+  }
+}
+
+export function writeOptimistic(state) {
+  Cookies.set(cookieName, JSON.stringify(state), {
+    expires: EXPIRY_MONTHS * 30,
+    sameSite: 'lax',
+    secure: window.location.protocol === 'https:',
+  });
+}

data/app/jobs/consentful/application_job.rb

@@ -0,0 +1,4 @@
+module Consentful
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/consentful/application_mailer.rb

@@ -0,0 +1,6 @@
+module Consentful
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/consentful/application_record.rb

@@ -0,0 +1,8 @@
+module Consentful
+  # Engine base class. Deliberately inherits straight from ActiveRecord::Base
+  # rather than the host's ApplicationRecord, which may wire primary/replica
+  # connection switching the engine should not inherit.
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/consentful/consent_category.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Consentful
+  class ConsentCategory < ApplicationRecord
+    # Unprefixed table name (isolate_namespace would otherwise expect
+    # `consentful_consent_categories`); keeps parity with an extracting host.
+    self.table_name = "consent_categories"
+
+    has_many :consent_services, dependent: :restrict_with_error
+
+    validates :key, presence: true, uniqueness: true
+    validates :key,
+              inclusion: { in: ->(_) { Consentful.config.category_keys } },
+              if: -> { Consentful.config.category_keys.present? }
+    validates :name, presence: true
+    validates :position, presence: true, numericality: { only_integer: true }
+
+    default_scope { order(position: :asc) }
+    scope :required_categories, -> { where(required: true) }
+  end
+end

data/app/models/consentful/consent_copy_version.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Consentful
+  class ConsentCopyVersion < ApplicationRecord
+    self.table_name = "consent_copy_versions"
+
+    STATUSES = { draft: 0, published: 1, archived: 2 }.freeze
+
+    has_many :consent_records, dependent: :restrict_with_error
+
+    enum :status, STATUSES
+
+    validates :digest, presence: true
+
+    before_validation :recalculate_digest
+
+    default_scope { order(created_at: :desc) }
+
+    def self.current
+      published.first
+    end
+
+    # `published_by` is a free-form identity string (e.g. an admin email)
+    # resolved by the host via Consentful.config.identify — not an FK.
+    def publish!(published_by = nil)
+      transaction do
+        self.class.published.where.not(id:).find_each { |v| v.update!(status: :archived) }
+        update!(status: :published, published_at: Time.current, published_by:)
+      end
+    end
+
+    def archive!
+      update!(status: :archived)
+    end
+
+    private
+
+    def recalculate_digest
+      payload = [
+        banner_title, banner_body, modal_intro,
+        accept_label, reject_label, manage_label, save_label,
+        category_blurbs.to_json
+      ].join("|")
+      self.digest = Digest::SHA256.hexdigest(payload)
+    end
+  end
+end

data/app/models/consentful/consent_record.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Consentful
+  class ConsentRecord < ApplicationRecord
+    self.table_name = "consent_records"
+
+    SOURCES = {
+      banner_accept_all: 0,
+      banner_reject_all: 1,
+      banner_save: 2,
+      preference_centre: 3,
+      expiry_reprompt: 4
+    }.freeze
+
+    belongs_to :consent_copy_version
+
+    enum :source, SOURCES
+
+    validates :visitor_uuid, presence: true
+    validates :recorded_at, presence: true
+
+    before_validation :default_recorded_at, on: :create
+
+    scope :for_visitor, ->(uuid) { where(visitor_uuid: uuid) }
+    scope :within, ->(range) { where(recorded_at: range) }
+
+    private
+
+    def default_recorded_at
+      self.recorded_at ||= Time.current
+    end
+  end
+end

data/app/models/consentful/consent_service.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Consentful
+  class ConsentService < ApplicationRecord
+    self.table_name = "consent_services"
+
+    LOADER_KINDS = { rails_partial: 0, gtm_tag: 1, inline_view: 2, external_only: 3 }.freeze
+
+    LOADER_KIND_LABELS = {
+      "rails_partial" => "Site-wide tag (managed in code)",
+      "gtm_tag" => "Google Tag Manager",
+      "inline_view" => "Single-page tag",
+      "external_only" => "External resource (no tag)"
+    }.freeze
+
+    REQUIRED_DISCLOSURE_FIELDS = %i[description processing_company_name legal_basis retention_period processing_location].freeze
+
+    belongs_to :consent_category
+
+    enum :loader_kind, LOADER_KINDS
+
+    validates :name, presence: true
+    validates :slug, presence: true, uniqueness: true,
+                     format: { with: /\A[a-z0-9_]+\z/, message: "may only contain lowercase letters, digits and underscores" }
+    validates :position, presence: true, numericality: { only_integer: true }
+
+    scope :active, -> { where(active: true) }
+    default_scope { order(:position, :name) }
+
+    def loader_kind_label
+      LOADER_KIND_LABELS.fetch(loader_kind, loader_kind.to_s)
+    end
+
+    def disclosure_complete?
+      REQUIRED_DISCLOSURE_FIELDS.all? { |f| public_send(f).present? }
+    end
+  end
+end

data/app/models/consentful/consent_state.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Consentful
+  # Plain value object over the consent cookie payload. Mirrors the JS
+  # implementation in the engine's state.js — keep the two in lockstep.
+  class ConsentState
+    EXPIRY = 12.months
+    EMPTY_COOKIE = {
+      "version_id" => nil,
+      "categories" => {},
+      "services" => {},
+      "recorded_at" => nil
+    }.freeze
+
+    attr_reader :version_id, :categories, :services, :recorded_at
+
+    def self.from_cookie(raw)
+      payload = parse(raw)
+      new(
+        version_id: payload["version_id"],
+        categories: payload["categories"] || {},
+        services: payload["services"] || {},
+        recorded_at: payload["recorded_at"]
+      )
+    end
+
+    def self.empty
+      new(version_id: nil, categories: {}, services: {}, recorded_at: nil)
+    end
+
+    def self.parse(raw)
+      return EMPTY_COOKIE if raw.blank?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      EMPTY_COOKIE
+    end
+
+    def initialize(version_id:, categories:, services:, recorded_at:)
+      @version_id = version_id
+      @categories = (categories || {}).transform_keys(&:to_s)
+      @services = (services || {}).transform_keys(&:to_s)
+      @recorded_at = recorded_at
+    end
+
+    def allowed?(service)
+      return true if service.consent_category&.required?
+
+      override = @services[service.slug]
+      return override unless override.nil?
+
+      !!@categories[service.consent_category.key]
+    end
+
+    def category_allowed?(category_key)
+      key = category_key.to_s
+      return true if key == Consentful.config.required_category_key
+
+      !!@categories[key]
+    end
+
+    def expired?
+      return true if @recorded_at.nil?
+
+      Time.zone.at(@recorded_at) < EXPIRY.ago
+    rescue TypeError, ArgumentError
+      true
+    end
+
+    def matches_version?(published_version)
+      return false if published_version.nil? || @version_id.nil?
+
+      @version_id.to_i == published_version.id
+    end
+
+    def recorded?
+      @version_id.present? && @recorded_at.present?
+    end
+  end
+end

data/app/models/consentful/consent_visitor_link.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Consentful
+  class ConsentVisitorLink < ApplicationRecord
+    self.table_name = "consent_visitor_links"
+
+    # Engine ships `email` only; hosts extend via
+    # Consentful.config.visitor_identifier_types in an initializer.
+    enum :identifier_type, Consentful.config.visitor_identifier_types
+
+    validates :visitor_uuid, presence: true
+    validates :identifier_value, presence: true,
+                                 uniqueness: { scope: [ :visitor_uuid, :identifier_type ] }
+    validates :linked_at, presence: true
+
+    before_validation :default_linked_at, on: :create
+
+    scope :for_value, ->(type, value) { where(identifier_type: type, identifier_value: value) }
+
+    private
+
+    def default_linked_at
+      self.linked_at ||= Time.current
+    end
+  end
+end

data/app/presenters/consentful/consent_record_presenter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Consentful
+  class ConsentRecordPresenter
+    ALLOWED = "allowed"
+    DENIED = "denied"
+
+    def initialize(record)
+      @record = record
+    end
+
+    def email_text
+      [
+        header,
+        summary_block,
+        categories_block,
+        service_overrides_block,
+        context_block,
+        copy_text_block
+      ].compact.join("\n\n")
+    end
+
+    private
+
+    attr_reader :record
+
+    def header
+      "Consent event recorded #{record.recorded_at.strftime('%Y-%m-%d %H:%M:%S')}"
+    end
+
+    def summary_block
+      [
+        "Source: #{record.source.to_s.humanize}",
+        "Visitor reference: #{record.visitor_uuid}",
+        "Copy version: ##{record.consent_copy_version_id}"
+      ].join("\n")
+    end
+
+    def categories_block
+      return if record.category_choices.blank?
+
+      lines = record.category_choices.map { |key, value| "  - #{key}: #{value ? ALLOWED : DENIED}" }
+      "Categories chosen:\n#{lines.join("\n")}"
+    end
+
+    def service_overrides_block
+      return if record.service_overrides.blank?
+
+      lines = record.service_overrides.map { |slug, value| "  - #{slug}: #{value ? ALLOWED : DENIED}" }
+      "Per-service overrides:\n#{lines.join("\n")}"
+    end
+
+    def context_block
+      parts = []
+      parts << "User agent: #{record.user_agent}" if record.user_agent.present?
+      parts << "Referer: #{record.referer}" if record.referer.present?
+      return if parts.empty?
+
+      parts.join("\n")
+    end
+
+    def copy_text_block
+      version = record.consent_copy_version
+      return if version.nil?
+
+      lines = [ "Copy shown to the visitor:" ]
+      lines << "  Title: #{version.banner_title}" if version.banner_title.present?
+      lines << "  Body: #{version.banner_body}" if version.banner_body.present?
+      lines << "  Modal intro: #{version.modal_intro}" if version.modal_intro.present?
+      lines.join("\n")
+    end
+  end
+end

data/app/services/consentful/dashboard_report.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Consentful
+  class DashboardReport
+    DEFAULT_DAYS = 30
+
+    attr_reader :days, :since
+
+    def initialize(days: nil)
+      @days = (days.presence&.to_i || DEFAULT_DAYS).clamp(1, 365)
+      @since = @days.days.ago
+    end
+
+    def total_records
+      @total_records ||= scope.count
+    end
+
+    def category_acceptance
+      @category_acceptance ||= ConsentCategory.order(:position).map do |category|
+        accepted = scope.where("category_choices ->> ? = 'true'", category.key).count
+        { category:, accepted:, total: total_records, rate: percentage(accepted, total_records) }
+      end
+    end
+
+    def source_breakdown
+      counts = scope.group(:source).count
+      ConsentRecord.sources.keys.map do |source|
+        count = counts.fetch(source, 0)
+        { source: source.to_sym, count:, rate: percentage(count, total_records) }
+      end
+    end
+
+    private
+
+    def scope
+      @scope ||= ConsentRecord.within(@since..Time.current)
+    end
+
+    def percentage(numerator, denominator)
+      return 0.0 if denominator.zero?
+
+      (numerator * 100.0 / denominator).round(1)
+    end
+  end
+end

data/app/services/consentful/sar_lookup.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Consentful
+  # Resolves a SAR enquiry (email or visitor UUID) into every consent_record
+  # we hold for that subject, with each event's copy version snapshot inlined
+  # so the response shows exactly what the visitor saw when they consented.
+  #
+  # Two entry points:
+  #   - Email: looked up via consent_visitor_links → all matching visitor UUIDs
+  #   - Visitor UUID: used directly
+  class SarLookup
+    attr_reader :email, :visitor_uuid
+
+    def initialize(email: nil, visitor_uuid: nil)
+      @email = Consentful.normalize_value(:email, email).presence
+      @visitor_uuid = visitor_uuid.to_s.strip.presence
+    end
+
+    def given_any_input?
+      @email.present? || @visitor_uuid.present?
+    end
+
+    def visitor_uuids
+      @visitor_uuids ||=
+        if @visitor_uuid
+          [ @visitor_uuid ]
+        elsif @email
+          ConsentVisitorLink.for_value(:email, @email).pluck(:visitor_uuid).uniq
+        else
+          []
+        end
+    end
+
+    def records
+      @records ||= ConsentRecord
+                   .includes(:consent_copy_version)
+                   .where(visitor_uuid: visitor_uuids)
+                   .order(recorded_at: :desc)
+    end
+
+    def linked_identifiers
+      @linked_identifiers ||= ConsentVisitorLink
+                              .where(visitor_uuid: visitor_uuids)
+                              .order(linked_at: :asc)
+    end
+  end
+end

data/app/views/consentful/admin/categories/edit.html.erb

@@ -0,0 +1,22 @@
+<h1>Edit category</h1>
+
+<%= form_with model: @category, scope: :consent_category, url: admin_category_path(@category) do |f| %>
+  <div class="cf-card">
+    <div class="cf-field">
+      <label>Key</label>
+      <input type="text" value="<%= @category.key %>" disabled>
+      <p class="cf-hint">The key is fixed; it identifies the category in cookies and code.</p>
+    </div>
+    <div class="cf-field"><%= f.label :name %><%= f.text_field :name %></div>
+    <div class="cf-field"><%= f.label :description %><%= f.text_area :description %></div>
+    <div class="cf-field">
+      <%= f.label :gtag_keys, "Google consent-mode signals" %>
+      <%= f.text_field :gtag_keys, value: @category.gtag_keys.join(", ") %>
+      <p class="cf-hint">Comma-separated, e.g. analytics_storage, ad_storage.</p>
+    </div>
+    <div class="cf-actions">
+      <%= f.submit "Save", class: "cf-btn cf-btn--primary" %>
+      <%= link_to "Cancel", admin_categories_path, class: "cf-btn" %>
+    </div>
+  </div>
+<% end %>

data/app/views/consentful/admin/categories/index.html.erb

@@ -0,0 +1,17 @@
+<h1>Categories</h1>
+
+<table class="cf-table">
+  <thead><tr><th>Position</th><th>Key</th><th>Name</th><th>Required</th><th>Consent-mode signals</th><th></th></tr></thead>
+  <tbody>
+    <% @categories.each do |category| %>
+      <tr>
+        <td><%= category.position %></td>
+        <td><code><%= category.key %></code></td>
+        <td><%= category.name %></td>
+        <td><%= category.required? ? "Yes" : "No" %></td>
+        <td class="cf-muted"><%= category.gtag_keys.join(", ") %></td>
+        <td><%= link_to "Edit", edit_admin_category_path(category), class: "cf-btn" %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/consentful/admin/copy_versions/_form.html.erb

@@ -0,0 +1,34 @@
+<%= form_with model: @version, scope: :consent_copy_version,
+      url: (@version.persisted? ? admin_copy_version_path(@version) : admin_copy_versions_path) do |f| %>
+  <% if @version.errors.any? %>
+    <div class="cf-flash cf-flash--alert"><%= @version.errors.full_messages.to_sentence %></div>
+  <% end %>
+
+  <div class="cf-card">
+    <h2>Banner &amp; modal copy</h2>
+    <div class="cf-field"><%= f.label :banner_title %><%= f.text_field :banner_title %></div>
+    <div class="cf-field"><%= f.label :banner_body %><%= f.text_area :banner_body %></div>
+    <div class="cf-field"><%= f.label :modal_intro %><%= f.text_area :modal_intro %></div>
+    <div class="cf-field"><%= f.label :accept_label %><%= f.text_field :accept_label %></div>
+    <div class="cf-field"><%= f.label :reject_label %><%= f.text_field :reject_label %></div>
+    <div class="cf-field"><%= f.label :manage_label %><%= f.text_field :manage_label %></div>
+    <div class="cf-field"><%= f.label :save_label %><%= f.text_field :save_label %></div>
+  </div>
+
+  <% if (@version.category_blurbs || {}).any? %>
+    <div class="cf-card">
+      <h2>Category blurbs</h2>
+      <% @version.category_blurbs.each do |key, blurb| %>
+        <div class="cf-field">
+          <label><%= key.to_s.humanize %></label>
+          <%= text_area_tag "consent_copy_version[category_blurbs][#{key}]", (blurb.is_a?(Hash) ? blurb["description"] : blurb) %>
+        </div>
+      <% end %>
+    </div>
+  <% end %>
+
+  <div class="cf-actions">
+    <%= f.submit (@version.persisted? ? "Save draft" : "Create draft"), class: "cf-btn cf-btn--primary" %>
+    <%= link_to "Cancel", admin_copy_versions_path, class: "cf-btn" %>
+  </div>
+<% end %>

data/app/views/consentful/admin/copy_versions/edit.html.erb

@@ -0,0 +1,2 @@
+<h1>Edit draft #<%= @version.id %></h1>
+<%= render "form" %>

data/app/views/consentful/admin/copy_versions/index.html.erb

@@ -0,0 +1,34 @@
+<h1>Consent copy versions</h1>
+
+<div class="cf-actions" style="margin-bottom:16px;">
+  <%= link_to "New draft", new_admin_copy_version_path, class: "cf-btn cf-btn--primary" %>
+</div>
+
+<table class="cf-table">
+  <thead><tr><th>ID</th><th>Status</th><th>Banner title</th><th>Published</th><th>By</th><th>Actions</th></tr></thead>
+  <tbody>
+    <% @versions.each do |version| %>
+      <tr>
+        <td>#<%= version.id %></td>
+        <td><span class="cf-badge cf-badge--<%= version.status %>"><%= version.status %></span></td>
+        <td><%= version.banner_title %></td>
+        <td class="cf-muted"><%= version.published_at&.strftime("%Y-%m-%d %H:%M") %></td>
+        <td class="cf-muted"><%= version.published_by %></td>
+        <td>
+          <div class="cf-actions">
+            <%= link_to "View", admin_copy_version_path(version), class: "cf-btn" %>
+            <% if version.draft? %>
+              <%= link_to "Edit", edit_admin_copy_version_path(version), class: "cf-btn" %>
+              <%= button_to "Publish", publish_admin_copy_version_path(version), class: "cf-btn cf-btn--gold" %>
+              <%= button_to "Delete", admin_copy_version_path(version), method: :delete, class: "cf-btn cf-btn--danger", form: { data: { turbo_confirm: "Delete this draft?" } } %>
+            <% elsif version.published? %>
+              <%= button_to "Archive", archive_admin_copy_version_path(version), class: "cf-btn" %>
+            <% else %>
+              <%= button_to "Clone to draft", restore_admin_copy_version_path(version), class: "cf-btn" %>
+            <% end %>
+          </div>
+        </td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/app/views/consentful/admin/copy_versions/new.html.erb

@@ -0,0 +1,2 @@
+<h1>New draft</h1>
+<%= render "form" %>

data/app/views/consentful/admin/copy_versions/show.html.erb

@@ -0,0 +1,24 @@
+<h1>Copy version #<%= @version.id %> <span class="cf-badge cf-badge--<%= @version.status %>"><%= @version.status %></span></h1>
+
+<div class="cf-card">
+  <p><strong><%= @version.banner_title %></strong></p>
+  <p><%= @version.banner_body %></p>
+  <p class="cf-muted"><%= @version.modal_intro %></p>
+  <p class="cf-muted">Buttons: <%= [@version.accept_label, @version.reject_label, @version.manage_label, @version.save_label].compact_blank.join(" · ") %></p>
+</div>
+
+<div class="cf-card">
+  <p class="cf-muted">Content digest</p>
+  <code><%= @version.digest %></code>
+  <button type="button" class="cf-btn"
+          data-controller="consentful--clipboard"
+          data-consentful--clipboard-text-value="<%= @version.digest %>"
+          data-action="consentful--clipboard#copy">Copy digest</button>
+</div>
+
+<div class="cf-actions">
+  <%= link_to "Back", admin_copy_versions_path, class: "cf-btn" %>
+  <% if @version.draft? %>
+    <%= link_to "Edit", edit_admin_copy_version_path(@version), class: "cf-btn cf-btn--primary" %>
+  <% end %>
+</div>