testimonials 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cbc7f22314c712ecb0e1eb5d92a3d66981193bc1fc19f8664f635d381db0045
-  data.tar.gz: '020981c67a45702104ebf9cdfd9f685ffc17d44653a3476560c0fb662176e445'
+  metadata.gz: d114855497d2d5186be09b6e76bab5f0d78e079012cfb765dd2399b61271e191
+  data.tar.gz: 0c3c906e8dd2aa883cf0261565b2c4f118c0ab8825c06683cbce18f4e59e3a17
 SHA512:
-  metadata.gz: 1ca4a49fd102d401ae88b344c951655e68e88af3fb0da1a11819b7b600edb9ad11543feb5440a25f2127e138f4da54d9d7447a3b260a79d7e3cb59b5abcdbfb2
-  data.tar.gz: d8c94fe02b56b3e91adf3eb39e1c87e88b70d4f0d9ed4102e8058901b019f0a1c5fb4d1d02327be255c18b5ca58afedae06e7386efd58978d16d017fde1bc8d5
+  metadata.gz: b9a26a9dd5f656c84cf657ed34bda8f130d3783be1efc98987d8bf438abb25728b6c34dc8c62b28e6e39a65a9a117baf411542da563ddfe9549b96edf1e545a9
+  data.tar.gz: de494a843ba1747d54a500815eaa2e212b99bc66b5302f6e59aed64f0ea7afba73a1257af1967a5052e441db5a59f6ba56ec9cb578938e18e91450f4d761f88d

data/AGENTS.md

@@ -5,7 +5,7 @@ Instructions for coding agents. Two audiences:
 - **[Installing testimonials into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add testimonials, reviews, or NPS.
 - **[Working on the gem itself](#working-on-the-gem-itself)** — you are working in this repository.
 
-Requirements: Ruby >= 3.2, Rails >= 7.1. Active Storage only for video and avatar uploads.
+Requirements: Ruby >= 3.2, Rails >= 7.1 and < 9. Active Storage only for video and avatar uploads.
 
 If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show testimonials)/AGENTS.md"`.
 
@@ -196,8 +196,14 @@ Turbo Drive and nonce-based CSP work out of the box; the widget config rides in
 
 ## Working on the gem itself
 
+The development toolchain is pinned to Ruby 4.0.5 in `mise.toml`. Do not use
+macOS's `/usr/bin/ruby`. In shells, hooks, or automation where mise activation
+is uncertain, explicitly prepend the configured Ruby, for example
+`PATH="$(mise where ruby)/bin:$PATH" bundle exec rake test`.
+
 ```bash
 bundle exec rake test            # minitest, dummy app under test/dummy
+bundle exec rake test:system     # real Chrome: NPS, testimonial, moderation, public read
 bundle exec rubocop             # must be clean
 BUNDLE_GEMFILE=gemfiles/rails_7.1.gemfile bundle exec rake test   # 7.1, 7.2, 8.0, 8.1 in gemfiles/
 ```

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 1.0.0 - 2026-08-11
+
+- **The 1.x record names are settled.** `Testimonials::Testimonial`,
+  `Testimonials::NpsResponse`, and `Testimonials::PromptEvent` are now
+  documented as the stable model constants rather than being hidden behind a
+  generic `Post` name. Their existing optional-install boundaries are
+  unchanged.
+- **A real Chrome test now proves the revenue-adjacent path:** an NPS promoter
+  is offered the testimonial form, submits text with public consent, lands in
+  pending moderation, is approved, and appears through the public read API
+  without leaking email. Capybara and Selenium are development/test
+  dependencies only.
+- **Uploaded videos, posters, and avatars stay behind the engine gate.** Media
+  responses now stream full and byte-range data directly after authorization
+  instead of redirecting to a reusable signed Active Storage URL. Code that
+  inspected a media response's `Location` header must consume the engine URL
+  directly; browser `<video>` and image URLs are unchanged.
+- **Hosts that load Action View from an initializer boot normally.** The widget
+  helper is loaded from `lib` before the engine registers its Action View hook;
+  `testimonials_tag` and the opener helpers are unchanged.
+- Added a security policy documenting stored testimonial, NPS, prompt-event,
+  consent, media, deletion, and retention boundaries. GitHub private
+  vulnerability reporting is the disclosure channel. Submitted page URLs now
+  accept only HTTP(S) and drop query strings/fragments before storage, keeping
+  tokens out of the database and executable schemes out of dashboard links.
+- Supported combinations are Ruby 3.2 through 4.0 and Rails 7.1 through 8.1;
+  Rails now has a `< 9` upper bound. Release validation runs the browser test,
+  lint and JavaScript checks, builds the gem, verifies RubyGems indexing, and
+  creates the GitHub Release.
+- Existing 0.x installs need no migration, initializer change, constant alias,
+  or model rename. The new Rails upper bound and non-redirecting media response
+  are the only compatibility costs.
+
 ## 0.9.1
 
 - **The demo data now teaches responsible collection.** Its testimonials cover

data/README.md

@@ -66,7 +66,8 @@ refreshes those records instead of duplicating them.
 > The dashboard defaults to **development only**. Set `authorize_admin` before
 > you deploy — see [Configure](#configure).
 
-Ruby >= 3.2 · Rails >= 7.1 · Active Storage only if you want video/avatar uploads.
+Ruby >= 3.2 · Rails >= 7.1 and < 9 · Active Storage only if you want
+video/avatar uploads.
 
 Installing with a coding agent? Point it at [AGENTS.md](AGENTS.md) — the same
 steps in the order an agent needs them, plus the gates it tends to get wrong
@@ -240,7 +241,7 @@ playback, feature toggle, and a **Best line** picker.
 <img src="https://raw.githubusercontent.com/yshmarov/testimonials/main/docs/screenshots/dashboard-show.jpg" alt="A single testimonial in the dashboard: video playback, best-line picker, attribution metadata, and approve/archive/feature/delete actions" width="620">
 
 Every submission keeps its provenance — who sent it, the exact consent text
-they agreed to, the page, locale, browser, timestamp. **Best line** is the only
+they agreed to, the query-free page URL, locale, browser, timestamp. **Best line** is the only
 thing you write: the customer's words stay verbatim, you just choose which
 sentence your landing page pulls out.
 
@@ -255,6 +256,8 @@ Admin-only by default. `config.public_api = true` serves them without auth
 (CORS `*`) — ideal for a static marketing site rendering your wall of love at
 build time. **Emails and author ids are never serialized.** Video and avatar
 files go through the same gate, with Range support so `<video>` just works.
+The media response stays on that authorized engine URL with a private,
+`no-store` cache policy; it never redirects to a reusable signed blob URL.
 
 ## Rendering what you collect
 
@@ -358,6 +361,49 @@ collection — so nothing changes until you set `config.tenant`.
 
 </details>
 
+## Compatibility and public API
+
+The following are the model and integration contracts that 1.x will keep
+stable under semantic versioning:
+
+- `Testimonials::Testimonial`, including `KINDS`, `STATUSES`, `SOURCES`, its
+  persisted fields, attachment predicates, status predicates, `for_tenant`,
+  `newest_first`, `approved`, `publishable`, `featured_first`, `display_name`,
+  and `quote`.
+- `Testimonials::NpsResponse`, including its persisted fields, `for_tenant`,
+  `newest_first`, `promoter?`, `passive?`, `detractor?`, `.score`, and `.band`
+  when NPS is installed.
+- `Testimonials::PromptEvent`, including `KINDS`, `ACTIONS`, its persisted
+  fields, `.eligible?`, and `.record!` when prompt events are installed.
+- `has_testimonials`, `Testimonials.configure`, `mount_testimonials`,
+  `testimonials_tag`, the opener helpers/attributes, and `testimonial_prompt!`.
+- `config.on_submit` and `config.on_detractor`, each receiving the documented
+  saved record.
+
+Those domain model names are intentional and will not become a generic `Post`
+during 1.x. Engine controllers, partials, CSS classes, generated HTML, and
+widget implementation objects are private. Incompatible changes to the public
+list above wait for a new major version; a deprecation normally ships first.
+
+### Upgrading from 0.x
+
+Version 1.0.0 keeps the existing domain models and schema. There is no
+migration, initializer change, compatibility alias, or rename: continue using
+`Testimonials::Testimonial`, `Testimonials::NpsResponse`, and
+`Testimonials::PromptEvent`. Rails 9 is excluded until a 1.x release explicitly
+adds it. Media URLs are unchanged, but their responses now contain the gated
+bytes instead of redirecting to an Active Storage URL.
+
+## Security and deletion
+
+See [SECURITY.md](https://github.com/yshmarov/testimonials/blob/main/SECURITY.md)
+for private vulnerability reporting and the stored-data, consent, media,
+deletion, and retention boundaries. In short: the public API is off by default;
+when enabled it returns only approved, publicly consented records without email
+or author ids. Deleting the live testimonial, NPS, and prompt-event rows is the
+host's responsibility, as are object-store, backup, analytics, cache, and export
+retention policies.
+
 ## Who's using it
 
 - [PaidCollabs](https://paidcollabs.com) — the screenshots above
@@ -369,9 +415,17 @@ add yourself.
 
 ```bash
 bundle exec rake test
+bundle exec rake test:system
 bundle exec rubocop
+node --check lib/testimonials/widget.js
+node --check lib/testimonials/dashboard.js
 ```
 
+The default suite covers the Rails engine contract. The system task drives a
+real headless Chrome session from NPS through promoter handoff, testimonial
+submission, moderation, and public read. CI runs Rails 7.1, 7.2, 8.0, and 8.1
+against Ruby 3.2 through 4.0.
+
 Bug reports and pull requests welcome. The fastest way to help is to install it
 in a real app and
 [tell me where it hurt](https://github.com/yshmarov/testimonials/issues).

data/Rakefile

@@ -5,7 +5,15 @@ require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
+  t.test_files = FileList['test/**/*_test.rb'].exclude('test/system/**/*')
+end
+
+namespace :test do
+  desc 'Run browser (system) tests'
+  Rake::TestTask.new(:system) do |task|
+    task.libs << 'test'
+    task.test_files = FileList['test/system/**/*_test.rb']
+  end
 end
 
 task default: :test

data/SECURITY.md

@@ -0,0 +1,57 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released for the latest 1.x version. If a report also
+affects the newest 0.x release, a backport may be published when the fix is
+small and the affected application cannot upgrade immediately.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability. Use
+[GitHub private vulnerability reporting](https://github.com/yshmarov/testimonials/security/advisories/new)
+and include the affected version, a minimal reproduction, impact, and any known
+workaround. Do not include credentials, session cookies, private application
+URLs, customer submissions, uploaded media, or production database contents.
+
+Public disclosure should wait until a fixed version is available and affected
+users have had a reasonable opportunity to upgrade.
+
+## Data and deployment boundary
+
+The public collection pages and widget are controlled by `config.enabled`;
+the dashboard is separately protected by `authorize_admin` and fails closed
+outside development until the host grants access. `config.public_api` is off by
+default. When enabled, it serves only approved testimonials carrying public
+consent and never serializes email or `author_id`.
+
+Testimonials can store their text, rating, best line, moderation status,
+consent choice and exact consent-text snapshot, attribution, source, page URL,
+user agent, locale, tenant key, timestamps, and optional video, poster, and
+avatar uploads. Page URLs are accepted only as HTTP(S) and stored without query
+strings or fragments. NPS responses can store the score, comment, attribution,
+the same query-free page URL, user agent, locale, tenant key, and timestamps.
+Prompt events store the prompt kind/action, author id or pseudonymous visitor
+token, tenant key, and timestamps.
+
+Uploaded media streams through the engine's authorization gate with private,
+non-stored responses; the route never redirects to a reusable signed blob URL.
+Hosts own the storage service, bucket policy, backups, retention periods,
+access controls, and incident response. Enabling the public API deliberately
+makes approved, publicly consented testimonial media readable to anyone who
+has its engine URL.
+
+Delete records when an application policy or customer request requires it:
+
+```ruby
+Testimonials::Testimonial.find(id).destroy!
+Testimonials::NpsResponse.find(id).destroy!
+Testimonials::PromptEvent.where(author_id: user.id.to_s).delete_all
+```
+
+Destroying a testimonial lets Rails apply its configured Active Storage
+attachment lifecycle. Confirm deletion separately in object storage, replicas,
+backups, caches, analytics, notifications, and exports; deleting live database
+rows does not rewrite those systems. Consent is evidence of the choice made at
+submission time, not a substitute for the host's withdrawal and retention
+process.

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module Testimonials
   # Who is asking, which tenant they are in, and the gates that answer both.
   #
@@ -41,6 +43,21 @@ module Testimonials
       Testimonial.for_tenant(current_tenant)
     end
 
+    # Browser URLs can carry password-reset tokens, signed ids, and campaign
+    # details in their query or fragment. Store only a safe HTTP(S) page origin
+    # and path; invalid or executable schemes become nil before the dashboard
+    # ever renders them as links.
+    def clean_page_url(value)
+      uri = URI.parse(value.to_s)
+      return unless uri.is_a?(URI::HTTP) && uri.host.present? && uri.userinfo.nil?
+
+      uri.query = nil
+      uri.fragment = nil
+      uri.to_s
+    rescue URI::InvalidURIError
+      nil
+    end
+
     def require_enabled
       head :forbidden unless Testimonials.enabled?(request)
     end

data/app/controllers/testimonials/media_controller.rb

@@ -5,34 +5,50 @@ module Testimonials
   # 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).
+  # streamed here after authorization. Keeping the browser on this route means
+  # an Active Storage URL cannot outlive the gate; Range support remains for
+  # video playback and seeking.
   class MediaController < ApplicationController
+    include ActiveStorage::Streaming if defined?(::ActiveStorage::Streaming)
+
     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)
+      stream(@testimonial.video_file)
     end
 
     def poster
       head :not_found and return unless @testimonial.poster_attached?
 
-      redirect_to main_app.rails_blob_path(@testimonial.poster, disposition: disposition)
+      stream(@testimonial.poster)
     end
 
     def avatar
       head :not_found and return unless @testimonial.avatar_attached?
 
-      redirect_to main_app.rails_blob_path(@testimonial.avatar, disposition: disposition)
+      stream(@testimonial.avatar)
     end
 
     private
 
-    # ?download=1 turns the redirect into a file download instead of
-    # inline playback.
+    def stream(attachment)
+      blob = attachment.blob
+      response.headers['Cache-Control'] = 'private, no-store'
+      if request.headers['Range'].present?
+        send_blob_byte_range_data(blob, request.headers['Range'], disposition: disposition)
+      else
+        response.headers['Accept-Ranges'] = 'bytes'
+        response.headers['Content-Length'] = blob.byte_size.to_s
+        send_blob_stream(blob, disposition: disposition)
+      end
+    end
+
+    # ?download=1 explicitly requests a file download. Without it we request
+    # inline playback; Active Storage may still force attachment disposition
+    # for content types outside the host's safe-inline allowlist.
     def disposition
       params[:download].present? ? 'attachment' : 'inline'
     end
@@ -48,7 +64,11 @@ module Testimonials
       # 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?
+
+      if Testimonials.config.public_api && @testimonial.approved? && @testimonial.consent_given?
+        response.set_header('Access-Control-Allow-Origin', '*')
+        return
+      end
 
       head :forbidden
     end

data/app/controllers/testimonials/nps_controller.rb

@@ -13,6 +13,7 @@ module Testimonials
       nps = NpsResponse.new(nps_params)
       nps.locale = I18n.locale.to_s
       nps.tenant = current_tenant
+      nps.page_url = clean_page_url(nps.page_url)
       nps.user_agent = request.user_agent
       attribute_author(nps)
 

data/app/controllers/testimonials/submissions_controller.rb

@@ -55,6 +55,7 @@ module Testimonials
       end
       testimonial.kind = wants_video?(testimonial) ? 'video' : 'text'
       testimonial.source = 'widget' unless Testimonial::SOURCES.include?(testimonial.source)
+      testimonial.page_url = clean_page_url(testimonial.page_url)
       testimonial.consent_text = Testimonials.consent_text_for(testimonial.consent_given?)
       testimonial.locale = I18n.locale.to_s
       testimonial.tenant = current_tenant

data/lib/testimonials/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Testimonials
-  VERSION = '0.9.1'
+  VERSION = '1.0.0'
 end

data/{app/helpers → lib}/testimonials/widget_helper.rb

@@ -1,15 +1,10 @@
 # frozen_string_literal: true
 
 module Testimonials
-  # Included into the host's ActionView. Drop `<%= testimonials_tag %>`
-  # before </body> in your layout; it renders nothing unless reviews are
-  # enabled for the request. The widget stays invisible until opened — by a
-  # `testimonial_prompt!` from a controller (throttled), by any element with a
-  # `data-testimonial-prompt` attribute, or by `window.Testimonials.open()`.
-  #
-  # `testimonials_button` renders a ready-made opener with a localized
-  # label ("Leave a review", or "Update your review" once the user has one),
-  # so hosts get a user-facing entry point without any i18n setup.
+  # Included into the host's ActionView. This lives under lib and is required
+  # before the engine registers its Action View load hook: a host initializer
+  # may load Action View before Rails sets up application autoloaders, when an
+  # app/helpers constant cannot be resolved yet.
   module WidgetHelper
     def testimonials_tag
       return unless Testimonials.enabled?(request)
@@ -23,19 +18,12 @@ module Testimonials
       ).html_safe
     end
 
-    # A plain, unstyled <button> so it picks up the host's own styles. Put it
-    # anywhere on a page that also renders testimonials_tag. Pass label: to
-    # override the localized default, and any other options (class:, etc.)
-    # through to the tag.
     def testimonials_button(label: nil, **)
       return unless Testimonials.enabled?(request)
 
       tag.button(label || testimonials_cta_label, type: 'button', 'data-testimonial-prompt': '', **)
     end
 
-    # The localized call-to-action on its own — "Leave a review", or "Update
-    # your review" once the user has one — for hosts composing their own
-    # opener markup (icons, list items) around a data-testimonial-prompt element.
     def testimonials_cta_label
       if testimonials_existing_testimonial
         I18n.t(:update_title, scope: :testimonials, default: 'Update your review')
@@ -52,8 +40,6 @@ module Testimonials
       @testimonials_author = Testimonials.config.current_user.call(request)
     end
 
-    # One review per signed-in user (per tenant): this is the record the widget
-    # opens pre-filled, and the one the create endpoint updates in place.
     def testimonials_existing_testimonial
       return @testimonials_existing_testimonial if defined?(@testimonials_existing_testimonial)
 
@@ -65,16 +51,10 @@ module Testimonials
         end
     end
 
-    # A prompt requested via testimonial_prompt! rides the flash, so it survives
-    # the usual redirect-after-create. It only reaches the page if the
-    # throttle ledger agrees — call testimonial_prompt! as often as you like.
     def testimonials_auto_open
       kind = flash[:testimonials_prompt].to_s
       return unless Testimonials::PromptEvent::KINDS.include?(kind)
       return if kind == 'nps' && !Testimonials.config.nps
-      # Without the ledger there is no record of who has been asked already, so
-      # an auto-open would reopen on every page a testimonial_prompt! reaches.
-      # An install with --skip-prompt-events opens on a click and nothing else.
       return unless Testimonials.config.prompt_events
 
       author = testimonials_author

data/lib/testimonials.rb

@@ -3,6 +3,7 @@
 require 'testimonials/version'
 require 'testimonials/configuration'
 require 'testimonials/widget'
+require 'testimonials/widget_helper'
 require 'testimonials/prompt_helper'
 require 'testimonials/has_testimonials'
 require 'testimonials/seeds'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: testimonials
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -16,6 +16,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -23,6 +26,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
 description: |
   A mountable Rails engine that collects customer testimonials — text and
   video — and NPS scores from inside your app. An iOS-style "Enjoying this
@@ -43,6 +49,7 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
+- SECURITY.md
 - app/controllers/concerns/testimonials/request_context.rb
 - app/controllers/testimonials/api/base_controller.rb
 - app/controllers/testimonials/api/stats_controller.rb
@@ -57,7 +64,6 @@ files:
 - app/controllers/testimonials/submissions_controller.rb
 - app/controllers/testimonials/testimonials_controller.rb
 - app/controllers/testimonials/widgets_controller.rb
-- app/helpers/testimonials/widget_helper.rb
 - app/models/testimonials/application_record.rb
 - app/models/testimonials/nps_response.rb
 - app/models/testimonials/prompt_event.rb
@@ -129,12 +135,13 @@ files:
 - lib/testimonials/version.rb
 - lib/testimonials/widget.js
 - lib/testimonials/widget.rb
+- lib/testimonials/widget_helper.rb
 homepage: https://github.com/yshmarov/testimonials
 licenses:
 - MIT
 metadata:
   homepage_uri: https://github.com/yshmarov/testimonials
-  source_code_uri: https://github.com/yshmarov/testimonials
+  source_code_uri: https://github.com/yshmarov/testimonials/tree/main
   changelog_uri: https://github.com/yshmarov/testimonials/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/yshmarov/testimonials/issues
   rubygems_mfa_required: 'true'
@@ -152,7 +159,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: 'Testimonials, reviews and NPS for Rails: in-app collection widget, public
   collection page, triage dashboard, and a read API.'