testimonials 0.7.10 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7ed14e07e92b6d456853cf8b9c04ece86f36d17873091f515f5c47e393894ca
-  data.tar.gz: c05b6be1e36b1592eabe270c18f7da4a15dafdca192a01141389141b76a37aca
+  metadata.gz: bfd44ded7b03a811fbbe8d6db999c3d04c9a1ca3d5401e1ae650fc407487e3a5
+  data.tar.gz: c683180efb5063687ca5ac8410caa6f51dff44ffe1de7ef65c83d30b4bc5052e
 SHA512:
-  metadata.gz: ff625ff280d473f959693892b942f52faa9b9e4f00ae139e7d07a94424d08da845ef387df6639cf1b37c536740aa0aa8d2350cd51416fc332a9b54bf22d810de
-  data.tar.gz: 2f721d94802015c6061a159d8e01797d09a2e1f5c453397f4519ed11508a464607009908685108b4c94d149336a5b1bf1d4d3998a0d04917402eee98a9780fa0
+  metadata.gz: 4ec04128d604bceebd38bec356b7511e4fa2823256ec1e6a59c5224d51aca6359bc8420d0f5e76bc303f46df001494b024e38b94ee888536fa4f97b0ff47f179
+  data.tar.gz: 94512ae9beeca12776e3aadcf5641e550b5733650c233d60e16ec449568d88ea38e4a4a84e36ceda03f2e0f80c133cd47315569ee14b73a64703183c9053d823

data/AGENTS.md

@@ -148,7 +148,7 @@ organization.testimonials.approved
 
 - **Do not hand-write the migration or the initializer.** Use the generators; the templates track the schema.
 - **Do not copy `widget.js` into `app/javascript`, or add a `<script>` tag for it.** `testimonials_tag` renders both tags itself, and the engine serves the code at `/testimonials/widget.js` with a content fingerprint. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
-- **Do not edit views inside the gem.** Override the dashboard's shell with `config.admin_layout = "admin/application"` if it needs to live inside an existing admin.
+- **Do not edit views inside the gem.** To put the dashboard inside an existing admin, set `config.base_controller_class = "Admin::BaseController"` (it inherits that controller's layout, helpers, authentication and request context) or, for the shell alone, `config.admin_layout = "admin/application"`. The dashboard's stylesheet and script are declared by its views, so both work with nothing else wired up.
 - **Do not check whether a table exists to decide if a feature is on.** `Testimonials.config.nps` and `Testimonials.config.prompt_events` are the source of truth, deliberately — nothing in the gem introspects the schema at runtime.
 - **Do not set config outside the initializer.** `rate_limit` in particular is read once when the controller class loads; assigning config in a controller or per-request is a global mutation across the process.
 - **Do not add `testimonials_tag` more than once per page,** and do not put it in a partial that some pages skip while still calling `testimonial_prompt!` — the prompt is consumed from the flash by whatever renders next.
@@ -163,6 +163,7 @@ Everything is optional; a fresh install works with zero config. Full list with c
 | `current_user`, `user_display`, `tenant`, `enabled` | no-ops | Lambdas over the raw request. |
 | `nps` | `true` | `false` = no prompt, no public NPS page, no dashboard tab, no `nps_score`. |
 | `prompt_events` | `true` | `false` = no prompt history, and therefore no auto-prompts at all. |
+| `base_controller_class` | `ActionController::Base` | Controller the DASHBOARD inherits. Public endpoints never do, so an admin base controller here cannot gate the widget. |
 | `reprompt_after`, `max_prompts` | `90.days`, `3` | Throttle for auto-prompts only. |
 | `video`, `avatars` | `true` | Need Active Storage; they self-disable when it isn't loaded. |
 | `public_collection` | `true` | `/testimonials/new` and `/testimonials/nps/new`. Shareable links. |
@@ -183,6 +184,8 @@ Turbo Drive and nonce-based CSP work out of the box; the widget config rides in
 | `no such table: testimonials_nps_responses` (or `..._prompt_events`) | A flag was flipped to `true` before running the matching generator and `db:migrate`. |
 | `/testimonials/nps_responses` 404s | `config.nps` is false. The rows are still there; flip it back to read them. |
 | Video recording missing | Active Storage not installed, or `config.video = false`. |
+| `NameError` for a host helper in the dashboard | `isolate_namespace` scopes `helper` to the engine. Use `config.base_controller_class` so the dashboard inherits your helpers, rather than `admin_layout` alone. |
+| `NotNullViolation` attaching a video on a uuid-keyed app | The tables were generated bigint. Set `config.generators` `primary_key_type` before installing, or migrate the tables to uuid. |
 | `undefined local variable current_user` in the initializer | A gate lambda treated its argument as a controller. It is a `request`. |
 
 ---

data/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.8.1
+
+- Dropped the redundant `(tenant, status)` index from the install and tenant
+  migration templates. A B-tree serves any leftmost prefix, so
+  `(tenant, status, consent_given)` already covers it, and every scope on the
+  model starts with `for_tenant` — carrying both only cost write time and disk.
+  Flagged by `active_record_doctor` in a host app.
+- Existing installs keep the index until they drop it themselves; nothing
+  breaks either way. To reclaim it:
+
+  ```ruby
+  class RemoveRedundantTestimonialsIndex < ActiveRecord::Migration[8.0]
+    def change
+      remove_index :testimonials_testimonials, %i[tenant status]
+    end
+  end
+  ```
+
+- A generator test now fails the build if any index is a leftmost prefix of
+  another on the same table.
+
+## 0.8.0
+
+- **`config.admin_layout` now works on its own.** The dashboard's stylesheet and
+  script were declared in the gem's layout, so replacing that layout dropped
+  both: the dashboard rendered unstyled with its delete confirmations and
+  auto-submitting filter dead. They move into the views (a shared
+  `testimonials/shared/_dashboard` partial), so every layout gets them with
+  nothing asked of the host.
+- **The dashboard stylesheet no longer claims selectors it does not own.** It
+  styled bare `body`, `a`, `table` and `*`, and its `.card`, `.badge`, `.tabs`
+  and `.container` are names Bootstrap and daisyUI use too, so a host that did
+  load it had its sidebar and topbar restyled. Component rules now nest inside a
+  `.tml-dashboard` wrapper the views render, every custom property is `--tml-`
+  prefixed, and `.container`/`.nav` became `.tml-page`/`.tml-nav`. The
+  full-viewport rules stay keyed to the `tm-index`/`tm-nps-index`/`tm-show` body
+  classes that only the gem's own layout sets, so inside a host admin the
+  dashboard scrolls with the host's page instead of fighting it for the
+  viewport. Two tests fail the build if a selector or property escapes again.
+- **Added `config.base_controller_class`.** Name the controller your own admin
+  inherits from and the dashboard adopts its layout, helpers, authentication and
+  request context — the things `admin_layout` cannot give you, and which hosts
+  were hand-wiring as a shim layout plus a concern to populate `Current`. Same
+  hook pgbus, avo and mission_control-jobs use. Default is unchanged.
+  Layout precedence with it: a host base controller keeps its own layout, unless the host also named an `admin_layout` explicitly.
+- **Migrations follow the host's `primary_key_type`,** the same
+  `Rails.configuration.generators` lookup Rails' own Active Storage, Action Text
+  and Action Mailbox migrations do. A uuid-keyed app has a uuid
+  `active_storage_attachments.record_id`, so bigint tables here could never hold
+  a video or avatar — `attach` raised `NotNullViolation`. A host that set
+  nothing gets no `id:` option and an identical migration to before.
+- **Dropped the `id: /\d+/` route constraints,** which were what forced the
+  tables to be bigint in the first place: uuid tables would have 404d show,
+  update, destroy and all three media routes. The constraint was never
+  load-bearing, since every fixed-name route is declared before the flat
+  `/:id` routes.
+- **`create` moved to `Testimonials::SubmissionsController`** and `POST` to the
+  mount path routes there. One controller used to serve both the widget's write
+  endpoint and the triage actions, which meant `base_controller_class` would
+  have put staff authentication in front of every member leaving a review. If
+  you referenced `Testimonials::TestimonialsController#create`, that is the
+  breaking change in this release; the URL is unchanged.
+- The shared request context (`current_author`, `current_tenant`,
+  `tenant_scope`, the gates) is now a `Testimonials::RequestContext` concern,
+  since the engine has two controller roots.
+
 ## 0.7.10
 
 - The prompt-history ledger is now optional too. `bin/rails generate

data/README.md

@@ -163,6 +163,8 @@ Everything is optional — a fresh install works with zero config. In
 | Option | Default | What it does |
 | --- | --- | --- |
 | `authorize_admin` | development only | **Who can read the dashboard.** Override before deploying |
+| `base_controller_class` | `ActionController::Base` | The controller the dashboard inherits — name your admin's and it adopts its layout, helpers and auth |
+| `admin_layout` | the gem's own | Just the shell, if you don't want the whole controller |
 | `app_name` | Rails app name | Shown as "Enjoying %{app}?" and in the questions |
 | `enabled` | everyone | Who gets the widget. `false` hides it and rejects posts |
 | `current_user` | `nil` | Attribute a submission to a user. Receives the request |

data/app/controllers/concerns/testimonials/request_context.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Who is asking, which tenant they are in, and the gates that answer both.
+  #
+  # A concern rather than inherited behaviour because the engine has two
+  # controller roots: the public endpoints hang off ActionController::Base, and
+  # the dashboard hangs off whatever the host set as `base_controller_class`.
+  # Both need everything here.
+  module RequestContext
+    extend ActiveSupport::Concern
+
+    private
+
+    def testimonials_admin_layout
+      Testimonials.config.admin_layout
+    end
+
+    def current_author
+      return @current_author if defined?(@current_author)
+
+      @current_author = Testimonials.config.current_user.call(request)
+    end
+
+    def current_author_id
+      current_author.respond_to?(:id) ? current_author.id : nil
+    end
+
+    # The tenant for this request (nil = the single global collection). Every
+    # read and write in the engine scopes to it, so a resolved-tenant admin
+    # only ever sees and writes their own tenant's records.
+    def current_tenant
+      return @current_tenant if defined?(@current_tenant)
+
+      @current_tenant = Testimonials.tenant(request)
+    end
+
+    # Every dashboard query and the create endpoint's one-per-user lookup start
+    # here, so neither can reach across tenants.
+    def tenant_scope
+      Testimonial.for_tenant(current_tenant)
+    end
+
+    def require_enabled
+      head :forbidden unless Testimonials.enabled?(request)
+    end
+
+    def render_rate_limited
+      message = I18n.t('testimonials.error_rate_limited',
+                       default: 'Too many submissions. Please wait a moment and try again.')
+      render json: { errors: [message] }, status: :too_many_requests
+    end
+
+    # Server-side gate for the dashboard. Default: development only.
+    def require_admin
+      return if Testimonials.admin?(request)
+
+      render plain: 'Forbidden. Set Testimonials.config.authorize_admin to grant access.',
+             status: :forbidden
+    end
+
+    # Guests get a permanent random token so the throttle ledger can
+    # remember them across visits. Signed-in users are keyed by author_id
+    # instead and never receive the cookie.
+    def ensure_visitor_token
+      return if current_author
+
+      cookies[:testimonials_vid].presence || begin
+        token = SecureRandom.base58(24)
+        cookies.permanent[:testimonials_vid] = { value: token, httponly: true, same_site: :lax }
+        token
+      end
+    end
+  end
+end

data/app/controllers/testimonials/application_controller.rb

@@ -1,63 +1,17 @@
 # frozen_string_literal: true
 
 module Testimonials
+  # Root of the engine's PUBLIC surface: widget.js, the submission endpoints,
+  # the prompt-event ledger, the public collection pages, media, and the read
+  # API. These stay on a plain ActionController::Base deliberately — a member
+  # posting a testimonial must not be routed through a host's admin controller,
+  # which would demand a staff session for the widget.
+  #
+  # The dashboard's root is DashboardController, and that is where
+  # `config.base_controller_class` applies.
   class ApplicationController < ActionController::Base
-    protect_from_forgery with: :exception
-
-    private
-
-    def testimonials_admin_layout
-      Testimonials.config.admin_layout
-    end
-
-    def current_author
-      return @current_author if defined?(@current_author)
-
-      @current_author = Testimonials.config.current_user.call(request)
-    end
-
-    def current_author_id
-      current_author.respond_to?(:id) ? current_author.id : nil
-    end
-
-    # The tenant for this request (nil = the single global collection). Every
-    # read and write in the engine scopes to it, so a resolved-tenant admin
-    # only ever sees and writes their own tenant's records.
-    def current_tenant
-      return @current_tenant if defined?(@current_tenant)
+    include RequestContext
 
-      @current_tenant = Testimonials.tenant(request)
-    end
-
-    def require_enabled
-      head :forbidden unless Testimonials.enabled?(request)
-    end
-
-    def render_rate_limited
-      message = I18n.t('testimonials.error_rate_limited',
-                       default: 'Too many submissions. Please wait a moment and try again.')
-      render json: { errors: [message] }, status: :too_many_requests
-    end
-
-    # Server-side gate for the dashboard. Default: development only.
-    def require_admin
-      return if Testimonials.admin?(request)
-
-      render plain: 'Forbidden. Set Testimonials.config.authorize_admin to grant access.',
-             status: :forbidden
-    end
-
-    # Guests get a permanent random token so the throttle ledger can
-    # remember them across visits. Signed-in users are keyed by author_id
-    # instead and never receive the cookie.
-    def ensure_visitor_token
-      return if current_author
-
-      cookies[:testimonials_vid].presence || begin
-        token = SecureRandom.base58(24)
-        cookies.permanent[:testimonials_vid] = { value: token, httponly: true, same_site: :lax }
-        token
-      end
-    end
+    protect_from_forgery with: :exception
   end
 end

data/app/controllers/testimonials/dashboard_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Root of the STAFF surface: the testimonial queue and the NPS pages.
+  #
+  # Inherits from `config.base_controller_class` — by default a plain
+  # ActionController::Base, which is why `authorize_admin` exists. Point it at
+  # the controller your own admin already inherits from and the dashboard picks
+  # up that stack wholesale: your layout, your helpers, your authentication,
+  # and whatever request context your before_actions establish (a `Current`
+  # attribute the layout reads, say). `config.admin_layout` only ever solved
+  # the first of those.
+  #
+  # Only the dashboard hangs off it. The widget's endpoints stay on
+  # ApplicationController, so wiring an admin base controller here can never
+  # demand a staff session from a member leaving a review.
+  class DashboardController < Testimonials.base_controller
+    include RequestContext
+
+    # A host base controller brings its own layout, and declaring one here would
+    # override it — the dashboard would render in the gem's standalone shell
+    # inside an app that just told us where its admin lives. So the gem only
+    # claims the layout when it owns the decision: no host base controller, or a
+    # host that named an `admin_layout` explicitly.
+    layout :testimonials_admin_layout unless superclass != ActionController::Base &&
+                                             Testimonials.config.admin_layout ==
+                                             Configuration::DEFAULT_ADMIN_LAYOUT
+
+    before_action :require_admin
+
+    # `authorize_admin` is a gate of last resort, and it is the only one when
+    # the host supplied no base controller. When they did, its default is
+    # development-only, so a host whose base controller already authenticates
+    # staff should widen or replace it.
+    #
+    # CSRF likewise: a host base controller has configured it already, and
+    # declaring it twice would run the check twice.
+    protect_from_forgery with: :exception if superclass == ActionController::Base
+  end
+end

data/app/controllers/testimonials/nps_responses_controller.rb

@@ -2,12 +2,9 @@
 
 module Testimonials
   # The NPS side of the dashboard: overall score plus the response list.
-  class NpsResponsesController < ApplicationController
+  class NpsResponsesController < DashboardController
     PER_PAGE = 50
 
-    layout :testimonials_admin_layout
-
-    before_action :require_admin
     # An install run with --skip-nps has no table behind these pages, and the
     # nav already hides the tab whenever config.nps is off.
     before_action :require_nps

data/app/controllers/testimonials/submissions_controller.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # The widget's write endpoint: POST to the mount path.
+  #
+  # Public, so it stays on ApplicationController and never inherits a host's
+  # admin base controller — a member leaving a review must not be asked for a
+  # staff session. The dashboard's read/triage actions live in
+  # TestimonialsController, which does inherit it.
+  class SubmissionsController < ApplicationController
+    before_action :require_enabled
+
+    # Throttle the public endpoint per IP so one user or bot can't flood the
+    # table (a submission may carry a video). Uses the rate limiter built
+    # into Rails 7.2+ (backed by Rails.cache); on Rails 7.1 this is a no-op.
+    # Tune or disable via config.rate_limit — read once at boot.
+    if respond_to?(:rate_limit) && Testimonials.config.rate_limit
+      rate_limit(**Testimonials.config.rate_limit, only: :create, with: -> { render_rate_limited })
+    end
+
+    def create
+      testimonial = build_testimonial
+
+      error = attach_video(testimonial) || attach_avatar(testimonial)
+      return render json: { errors: [error] }, status: :unprocessable_entity if error
+
+      if testimonial.save
+        # Purge only after a valid save, so a failed update can't strand a
+        # review with its video already gone.
+        if remove_video? && testimonial.video_attached?
+          testimonial.video_file.purge
+          testimonial.poster.purge if testimonial.poster_attached?
+        end
+        record_submission
+        notify_host(testimonial)
+        head :created
+      else
+        render json: { errors: testimonial.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    # One review per signed-in user: a re-submission edits their existing
+    # review in place (the App Store model). The edit goes back through
+    # moderation, and the admin's best_line is cleared — it may no longer
+    # match the new wording. Guests have no reliable identity, so each guest
+    # submission stays a new record.
+    def build_testimonial
+      testimonial = existing_testimonial || Testimonial.new
+      testimonial.assign_attributes(testimonial_params)
+      if testimonial.persisted?
+        testimonial.status = 'pending'
+        testimonial.best_line = nil
+      end
+      testimonial.kind = wants_video?(testimonial) ? 'video' : 'text'
+      testimonial.source = 'widget' unless Testimonial::SOURCES.include?(testimonial.source)
+      testimonial.consent_text = Testimonials.consent_text_for(testimonial.consent_given?)
+      testimonial.locale = I18n.locale.to_s
+      testimonial.tenant = current_tenant
+      testimonial.user_agent = request.user_agent
+      attribute_author(testimonial)
+      testimonial
+    end
+
+    # One review per signed-in user, *per tenant*: the same person can leave a
+    # separate review in each tenant, but only one within any single tenant.
+    def existing_testimonial
+      return if current_author_id.blank?
+
+      tenant_scope.where(author_id: current_author_id.to_s).newest_first.first
+    end
+
+    # A fresh upload makes it a video review; on an edit without a new
+    # upload, an already-attached video stays — unless the user removed it.
+    def wants_video?(testimonial)
+      return true if params.dig(:testimonial, :video_file).present?
+
+      testimonial.video_attached? && !remove_video?
+    end
+
+    def remove_video?
+      params.dig(:testimonial, :remove_video).present? && params.dig(:testimonial, :video_file).blank?
+    end
+
+    def testimonial_params
+      params.require(:testimonial)
+            .permit(:body, :rating, :consent_given, :page_url, :source,
+                    :name, :email, :title_company)
+    end
+
+    # Signed-in users are attributed server-side — the widget never sends
+    # (and the endpoint never trusts) contact fields for them.
+    def attribute_author(testimonial)
+      author = current_author
+      return if author.nil?
+
+      testimonial.author_id = author.id.to_s if author.respond_to?(:id)
+      display = Testimonials.config.user_display.call(author) || {}
+      testimonial.name = display[:name].presence || testimonial.name
+      testimonial.email = display[:email].presence || testimonial.email
+      testimonial.title_company = display[:title_company].presence || testimonial.title_company
+    end
+
+    # Returns an error message, or nil when everything is fine.
+    def attach_video(testimonial)
+      file = params.dig(:testimonial, :video_file)
+      return nil if file.blank?
+      return error_label(:error_save) unless Testimonials.config.video_enabled?
+      return error_label(:error_video_too_large) if file.size > Testimonials.config.max_video_size
+      return error_label(:error_save) unless file.content_type.to_s.start_with?('video/', 'audio/')
+
+      testimonial.video_file.attach(file)
+      attach_poster(testimonial)
+      nil
+    end
+
+    # The poster rides with a new video upload. It's best-effort — a missing
+    # or malformed poster never blocks the testimonial. Attaching replaces any
+    # previous poster; a new video with no usable poster (e.g. an uploaded
+    # file, which we can't frame-grab) drops the stale one so it can't show a
+    # thumbnail from the wrong video.
+    def attach_poster(testimonial)
+      file = params.dig(:testimonial, :poster)
+      usable = file.present? && file.content_type.to_s.start_with?('image/') &&
+               file.size <= Testimonials.config.max_avatar_size
+
+      if usable
+        testimonial.poster.attach(file)
+      elsif testimonial.poster_attached?
+        testimonial.poster.purge
+      end
+    end
+
+    def attach_avatar(testimonial)
+      file = params.dig(:testimonial, :avatar)
+      return nil if file.blank?
+      return error_label(:error_save) unless Testimonials.config.avatars_enabled?
+      return error_label(:error_save) if file.size > Testimonials.config.max_avatar_size
+      return error_label(:error_save) unless file.content_type.to_s.start_with?('image/')
+
+      testimonial.avatar.attach(file)
+      nil
+    end
+
+    def record_submission
+      PromptEvent.record!(kind: 'testimonial', action: 'submitted', tenant: current_tenant,
+                          author_id: current_author_id, visitor_token: ensure_visitor_token)
+    end
+
+    # The host's hook must never turn a saved submission into a 500 — the
+    # testimonial is in the database; notification failures are the host's
+    # logs' problem.
+    def notify_host(record)
+      Testimonials.config.on_submit.call(record)
+    rescue StandardError => e
+      Rails.logger.error("testimonials: on_submit hook raised #{e.class}: #{e.message}")
+    end
+
+    def error_label(key)
+      defaults = {
+        error_save: 'Could not send. Please try again.',
+        error_video_too_large: 'The video is too large (max %{size} MB).'
+      }
+      I18n.t(key, scope: :testimonials, default: defaults[key],
+                  size: Testimonials.config.max_video_size / (1024 * 1024))
+    end
+  end
+end