testimonials 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c3a780f6ec2e1bfb53266936069312dc7821e8f1b28e437aa163e82bbf09bf9a
+  data.tar.gz: bf1d9e6f2e44617937ebb35bb8cd3d56528ee5486243c9ce1ceba939bf982b44
+SHA512:
+  metadata.gz: 212b640b1254e063aa7db13385842072e432cd0130503fd0f379115ac146151b9e450aa6dd47e599895815a3298cd169ad7795d5db2ede32a5f0d1548fb3fde6
+  data.tar.gz: 7b585a4caf94d6d70531e52eb0d0fca1d389ebcbe11a10638002b1a9eeee23ee0c976ee38392493719831da1bb30574cf8694151ca0199369c6901228706fd33

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release: in-app testimonial widget (text + video), public collection
+  page, prompt throttling, `testimonial_prompt!`, NPS with promoter auto-routing,
+  triage dashboard, read API (`/api/testimonials`, `/api/stats`), localized
+  best-practice questions.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Yaroslav Shmarov
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# testimonials
+
+[![Gem Version](https://img.shields.io/gem/v/testimonials)](https://rubygems.org/gems/testimonials)
+[![CI](https://github.com/yshmarov/testimonials-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/yshmarov/testimonials-engine/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](MIT-LICENSE)
+
+Testimonials, reviews and NPS for Rails. Self-hosted alternative to
+Testimonial.to / Senja / Delighted.
+
+`testimonials` collects customer testimonials — text and **video** — from
+inside your app with an iOS-style "Enjoying this app?" prompt, from a
+shareable public page, and from NPS promoters routed straight into the
+testimonial ask. Everything lands in your own database with a minimal
+dashboard to approve, feature, and pick each one’s best line. Display is **headless**: render
+approved testimonials with your own markup via the models or a JSON API —
+copy-paste examples included.
+
+- **Zero UI dependencies.** The widget is plain JavaScript and styles itself.
+  No Tailwind, no Stimulus, no importmap, no build step. Works with Turbo
+  Drive and strict nonce-based CSP out of the box.
+- **Prompt at the right moment.** Call `testimonial_prompt!` in a controller at
+  your success moments (subscription renewed, milestone hit). Built-in
+  throttling means you can call it liberally — nobody gets nagged.
+- **Real attribution.** Signed-in users are attributed server-side to your
+  user records; guests leave name and email. No external tool can do this.
+- **Video testimonials** recorded in the browser (MediaRecorder) with a
+  review step, or uploaded as a file. Plain multipart upload via Active
+  Storage.
+- **NPS built in.** 0–10 with a comment; promoters (9–10) are immediately
+  offered the testimonial form, detractors flow into `on_detractor` (pairs
+  well with [feedback_engine](https://github.com/yshmarov/feedback-engine)).
+- **Consent is first-class.** A consent checkbox with a stored text snapshot;
+  the API only ever serves approved **and** consented records, and never
+  emails.
+- **26 languages**, including localized best-practice guiding questions.
+
+## How it works
+
+1. Add `<%= testimonials_tag %>` to your layout. Nothing is visible until
+   the widget opens: from an eligible `testimonial_prompt!`, from any element with
+   `data-testimonial-prompt`, or from `window.Testimonials.open()`.
+2. The prompt starts as a small star card ("Enjoying MyApp? ★★★★★ / Not
+   now"). Tapping a star expands into the full form: guiding questions,
+   text, optional video recording, consent.
+3. Submissions land in `testimonials_testimonials` as `pending`. You
+   approve, feature, and pick best lines at the mount path (`/testimonials`).
+4. You render approved testimonials wherever you like — see
+   [`examples/`](examples/) for a wall of love, quote card, rating badge,
+   JSON-LD rich snippets, and a static-site (Astro) recipe.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+- Active Storage (only if you want video/avatar uploads)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "testimonials"
+```
+
+```bash
+bundle install
+bin/rails generate testimonials:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/testimonials.rb`, creates the
+migration, and mounts the engine at `/testimonials`. Then add the widget to your
+layout:
+
+```erb
+<%= testimonials_tag %>
+```
+
+## Prompting users
+
+```ruby
+class InvoicesController < ApplicationController
+  def create
+    # ...
+    testimonial_prompt! if current_user.invoices.count == 10  # a success moment
+    redirect_to invoices_path
+  end
+end
+```
+
+The widget auto-opens on the next rendered page **if** the throttle allows:
+
+- submitted a testimonial → never auto-prompted again
+- dismissed → not again within `reprompt_after` (default 90 days)
+- auto-prompted `max_prompts` times (default 3) → never again
+
+Explicit opens bypass throttling: any element with `data-testimonial-prompt`
+(or `data-testimonial-prompt="nps"`), or `window.Testimonials.open()` /
+`window.Testimonials.openNps()`.
+
+`testimonial_prompt!(:nps)` prompts for an NPS score instead.
+
+## Configuration
+
+Everything lives in `config/initializers/testimonials.rb`; every option has
+a working default. The essentials:
+
+```ruby
+Testimonials.configure do |config|
+  config.app_name = "SupeRails"
+  config.current_user = ->(request) { request.env["warden"]&.user }
+  config.user_display = ->(user) { { name: user.name, email: user.email } }
+  config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+  config.on_submit = ->(record) { SlackNotifier.ping(record) }
+  config.on_detractor = ->(nps) { FeedbackEngine::Feedback.create!(kind: "other", message: nps.comment.to_s) }
+end
+```
+
+### Guiding questions, localized
+
+The questions shown above the form ("How has %{app} helped you?") fight
+blank-page paralysis — they are prompts, not form fields. By default they
+come from the gem's own locale files, so all 26 languages get good questions
+with your app name interpolated. Override with literal strings or a lambda
+for host-side i18n:
+
+```ruby
+config.questions = ["What convinced you to try %{app}?", "What changed since?"]
+config.questions = -> { I18n.t("reviews.questions") }  # your own locale keys
+config.questions = []                                  # hide the section
+```
+
+## The public collection page
+
+`/testimonials/new` is a standalone, self-styled page for customers outside the
+app — drop the link into an email or DM. Guests leave name, email, optional
+title/company and photo. Disable with `config.public_collection = false`.
+
+## The read API
+
+- `GET /testimonials/api/testimonials` — approved + consented records only;
+  filters: `featured=1`, `min_rating=4`, `kind=video`, `limit=12`.
+- `GET /testimonials/api/stats` — `count`, `average_rating`, `ratings_count`,
+  `nps_score`.
+
+Admin-only by default. Set `config.public_api = true` to serve them without
+auth (CORS `*`) — ideal for a separate static marketing site that renders
+your wall of love at build time. Emails and author ids are never serialized.
+Video and avatar files are handed out by testimonial id through the same
+gate, with Range support so `<video>` tags just work.
+
+## NPS
+
+`testimonial_prompt!(:nps)` (or the widget API) asks the classic 0–10 question.
+Promoters are offered the testimonial form right away — but only if the
+testimonial throttle would allow it. Detractors trigger `on_detractor`.
+The dashboard shows your NPS score and every response at
+`/testimonials/nps_responses`. Disable with `config.nps = false`.
+
+## Dashboard
+
+Browse at the mount path: pending → approved → archived tabs, search,
+quick-approve, inline video playback, feature toggle, and a “Best line” picker —
+the customer's words are never editable, but you choose the pull-quote.
+Gated by `config.authorize_admin` (development-only until you set it).
+
+## Testing
+
+```bash
+bundle exec rake test
+bundle exec rubocop
+```
+
+## License
+
+MIT.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task default: :test

data/app/controllers/testimonials/api/base_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Testimonials
+  module Api
+    # Read-only JSON. With config.public_api the endpoints answer anyone
+    # (approved + consented records only, CORS open for static marketing
+    # sites); otherwise they answer only requests that pass authorize_admin.
+    class BaseController < ApplicationController
+      skip_forgery_protection
+
+      before_action :authorize_api
+      after_action :allow_cross_origin
+
+      private
+
+      def authorize_api
+        return if Testimonials.config.public_api
+        return if Testimonials.admin?(request)
+
+        head :forbidden
+      end
+
+      # Public testimonials are meant to be fetched from anywhere — a static
+      # marketing site at build time or in the browser.
+      def allow_cross_origin
+        response.set_header('Access-Control-Allow-Origin', '*') if Testimonials.config.public_api
+      end
+    end
+  end
+end

data/app/controllers/testimonials/api/stats_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Testimonials
+  module Api
+    # Powers rating badges: "★ 4.9 from 87 reviews".
+    class StatsController < BaseController
+      def show
+        scope = Testimonial.publishable
+        rated = scope.where.not(rating: nil)
+
+        render json: {
+          count: scope.count,
+          average_rating: rated.average(:rating)&.to_f&.round(2),
+          ratings_count: rated.count,
+          nps_score: (NpsResponse.score if Testimonials.config.nps)
+        }
+      end
+    end
+  end
+end

data/app/controllers/testimonials/api/testimonials_controller.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Testimonials
+  module Api
+    class TestimonialsController < BaseController
+      MAX_LIMIT = 100
+
+      def index
+        scope = Testimonial.publishable.featured_first
+        scope = scope.where(featured: true) if params[:featured].present?
+        scope = scope.where(kind: params[:kind]) if Testimonial::KINDS.include?(params[:kind])
+        scope = scope.where(rating: params[:min_rating].to_i..) if params[:min_rating].present?
+        limit = params[:limit].to_i.clamp(1, MAX_LIMIT)
+        limit = MAX_LIMIT if params[:limit].blank?
+
+        render json: { testimonials: scope.limit(limit).map { |t| serialize(t) } }
+      end
+
+      private
+
+      # Name, title and media only — never emails, never author ids. The
+      # customer consented to publication, not to leaking contact details.
+      def serialize(testimonial)
+        {
+          id: testimonial.id,
+          kind: testimonial.kind,
+          body: testimonial.body,
+          best_line: testimonial.best_line,
+          quote: testimonial.quote,
+          rating: testimonial.rating,
+          name: testimonial.name,
+          title_company: testimonial.title_company,
+          featured: testimonial.featured?,
+          created_at: testimonial.created_at.iso8601,
+          avatar_url: (testimonial_avatar_url(testimonial) if testimonial.avatar_attached?),
+          video_url: (testimonial_video_url(testimonial) if testimonial.video_attached?)
+        }
+      end
+    end
+  end
+end

data/app/controllers/testimonials/application_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Testimonials
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    private
+
+    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
+
+    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/collection_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # The standalone public collection page at "#{mount_path}/new" — the link
+  # you drop into an email or DM so customers outside the app can leave a
+  # testimonial. Toggled by config.public_collection (ON by default).
+  class CollectionController < ApplicationController
+    layout 'testimonials/collection'
+
+    def show
+      head :not_found and return unless Testimonials.config.public_collection
+      head :forbidden and return unless Testimonials.enabled?(request)
+
+      # A signed-in visitor edits their existing review instead of adding one.
+      @existing = current_author_id && Testimonial.where(author_id: current_author_id.to_s).newest_first.first
+    end
+  end
+end

data/app/controllers/testimonials/events_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # The widget reports auto-prompt lifecycle here: "shown" when it opened
+  # itself, "dismissed" when the user closed it without submitting.
+  # ("submitted" is recorded server-side by the create endpoints.) These
+  # events feed PromptEvent.eligible?, which is what keeps auto-prompts from
+  # nagging anyone.
+  class EventsController < ApplicationController
+    CLIENT_ACTIONS = %w[shown dismissed].freeze
+
+    before_action :require_enabled
+
+    def create
+      kind = params[:kind].to_s
+      action = params[:event_action].to_s
+      head :unprocessable_entity and return unless PromptEvent::KINDS.include?(kind) &&
+                                                   CLIENT_ACTIONS.include?(action)
+
+      PromptEvent.record!(kind: kind, action: action,
+                          author_id: current_author_id, visitor_token: ensure_visitor_token)
+      head :no_content
+    end
+  end
+end

data/app/controllers/testimonials/media_controller.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Hands out video and avatar files by testimonial id, so consumers never
+  # need to know about Active Storage. Admins can fetch anything; everyone
+  # else only reaches media of publishable (approved + consented)
+  # testimonials, and only when the read API is public. The actual bytes are
+  # served by Active Storage's own controllers (signed, expiring URLs, with
+  # Range support — video elements need that).
+  class MediaController < ApplicationController
+    before_action :set_testimonial
+    before_action :authorize_media
+
+    def video
+      head :not_found and return unless @testimonial.video_attached?
+
+      redirect_to main_app.rails_blob_path(@testimonial.video_file, disposition: disposition)
+    end
+
+    def avatar
+      head :not_found and return unless @testimonial.avatar_attached?
+
+      redirect_to main_app.rails_blob_path(@testimonial.avatar, disposition: disposition)
+    end
+
+    private
+
+    # ?download=1 turns the redirect into a file download instead of
+    # inline playback.
+    def disposition
+      params[:download].present? ? 'attachment' : 'inline'
+    end
+
+    def set_testimonial
+      @testimonial = Testimonial.find(params[:id])
+    end
+
+    def authorize_media
+      return if Testimonials.admin?(request)
+      # Authors can always see their own media — the widget replays their
+      # attached video when they edit their review.
+      return if current_author_id.present? && @testimonial.author_id == current_author_id.to_s
+      return if Testimonials.config.public_api && @testimonial.approved? && @testimonial.consent_given?
+
+      head :forbidden
+    end
+  end
+end

data/app/controllers/testimonials/nps_controller.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Testimonials
+  class NpsController < ApplicationController
+    before_action :require_enabled
+    before_action :require_nps
+
+    if respond_to?(:rate_limit) && Testimonials.config.rate_limit
+      rate_limit(**Testimonials.config.rate_limit, only: :create, with: -> { render_rate_limited })
+    end
+
+    def create
+      nps = NpsResponse.new(nps_params)
+      nps.locale = I18n.locale.to_s
+      nps.user_agent = request.user_agent
+      attribute_author(nps)
+
+      if nps.save
+        PromptEvent.record!(kind: 'nps', action: 'submitted',
+                            author_id: current_author_id, visitor_token: ensure_visitor_token)
+        notify_host(nps)
+        notify_detractor(nps) if nps.detractor?
+        render json: { offer_testimonial: offer_testimonial?(nps) }, status: :created
+      else
+        render json: { errors: nps.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def require_nps
+      head :forbidden unless Testimonials.config.nps
+    end
+
+    def nps_params
+      params.require(:nps).permit(:score, :comment, :email, :page_url)
+    end
+
+    def attribute_author(nps)
+      author = current_author
+      return if author.nil?
+
+      nps.author_id = author.id.to_s if author.respond_to?(:id)
+      display = Testimonials.config.user_display.call(author) || {}
+      nps.name = display[:name].presence
+      nps.email = display[:email].presence || nps.email
+    end
+
+    # A promoter gets the testimonial ask right away — but only if the
+    # throttle ledger would allow a testimonial prompt anyway.
+    def offer_testimonial?(nps)
+      nps.promoter? && PromptEvent.eligible?(
+        kind: 'testimonial',
+        author_id: current_author_id,
+        visitor_token: cookies[:testimonials_vid]
+      )
+    end
+
+    def notify_host(nps)
+      Testimonials.config.on_submit.call(nps)
+    rescue StandardError => e
+      Rails.logger.error("testimonials: on_submit hook raised #{e.class}: #{e.message}")
+    end
+
+    def notify_detractor(nps)
+      Testimonials.config.on_detractor.call(nps)
+    rescue StandardError => e
+      Rails.logger.error("testimonials: on_detractor hook raised #{e.class}: #{e.message}")
+    end
+  end
+end

data/app/controllers/testimonials/nps_responses_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # The NPS side of the dashboard: overall score plus the response list.
+  class NpsResponsesController < ApplicationController
+    PER_PAGE = 50
+
+    layout 'testimonials/application'
+
+    before_action :require_admin
+
+    def index
+      @score = NpsResponse.score
+      @total = NpsResponse.count
+      @promoters = NpsResponse.where(score: 9..10).count
+      @passives = NpsResponse.where(score: 7..8).count
+      @detractors = NpsResponse.where(score: 0..6).count
+
+      @page = [params[:page].to_i, 1].max
+      @responses = NpsResponse.newest_first.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
+      @more = @responses.size > PER_PAGE
+      @responses = @responses.first(PER_PAGE)
+    end
+  end
+end