testimonials 0.7.8 → 0.7.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f77889bc1fe3b99ca3b75dad0936498a35afa29249bceb5c9000ef090b275cfc
-  data.tar.gz: 0bd9fdedb0d9b11be9c4b8ebdea7277d4f45c249723b5c43dc93bb7b2e74cb7b
+  metadata.gz: f7ed14e07e92b6d456853cf8b9c04ece86f36d17873091f515f5c47e393894ca
+  data.tar.gz: c05b6be1e36b1592eabe270c18f7da4a15dafdca192a01141389141b76a37aca
 SHA512:
-  metadata.gz: 2b60920030a7e8099116b1d8abd8e31f98fbf9b984f4c3faaebf7fd3449ac232574016c0b0d5c62ea0ecd6647500e2646baf8264c657ed913df98ab7fa71c207
-  data.tar.gz: 3c5b5e7209197b41f28cb90240b3c232123ad91833e14be80031af275becf143f9376316d36857c9de7db844eb8630aa570de8bc09d0a14173a534da4f309980
+  metadata.gz: ff625ff280d473f959693892b942f52faa9b9e4f00ae139e7d07a94424d08da845ef387df6639cf1b37c536740aa0aa8d2350cd51416fc332a9b54bf22d810de
+  data.tar.gz: 2f721d94802015c6061a159d8e01797d09a2e1f5c453397f4519ed11508a464607009908685108b4c94d149336a5b1bf1d4d3998a0d04917402eee98a9780fa0

data/AGENTS.md

@@ -0,0 +1,207 @@
+# AGENTS.md
+
+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.
+
+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"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Decide two things first — they are install-time flags
+
+Both features can be added later, but skipping them now means smaller schema and less code reaching the database. Ask the user only if the answer isn't already obvious from their request.
+
+| Question | If no |
+| --- | --- |
+| Do they want NPS (the 0–10 "how likely are you to recommend" survey)? | `--skip-nps` |
+| Should the widget ever **open itself** — `testimonial_prompt!` at a success moment — rather than only on a click? | `--skip-prompt-events` |
+
+Default to a full install when unsure. "Just let users leave reviews from a button in the menu" is the common case for `--skip-prompt-events`.
+
+### 2. Install
+
+```bash
+bundle add testimonials
+bin/rails generate testimonials:install    # + any --skip-* flags from step 1
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/testimonials.rb`, one migration, and `mount_testimonials at: "/testimonials"` into `config/routes.rb`. Read the initializer it wrote — every option is documented there in comments, and it is the source of truth over any summary of it, including this file.
+
+Every `config.…` line below belongs inside the `Testimonials.configure do |config|` block in that initializer. Uncomment and edit in place rather than appending a second `configure` block.
+
+### 3. Wire the three things the generator cannot
+
+**a. The widget tag.** Nothing renders until this is on the page:
+
+```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
+<%= testimonials_tag %>
+```
+
+The helper is injected into ActionView by the engine — no include, no import, no asset pipeline entry. It renders nothing until the widget is opened, and it must be present on any page where the widget can open.
+
+**b. `authorize_admin` — do this before deploying.** The dashboard at `/testimonials` defaults to **development only**. It fails closed, so shipping without this is not an open door — it is a 403 telling you to set it.
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+**c. Attribution**, if the app has users. Optional, but without it every submission is a guest.
+
+```ruby
+config.current_user = ->(request) { request.env["warden"]&.user }   # Devise/Warden
+config.user_display = ->(user) { { name: user.name, email: user.email } }
+```
+
+> **Every gate receives the raw `request`, not a controller.** `current_user`, `authorize_admin`, `enabled` and `tenant` are lambdas over `ActionDispatch::Request`. Writing `->(request) { current_user }` is the single most common mistake here — that method does not exist in this scope. Resolve the user *from the request*: Warden env, a signed cookie, `Current.user` if the app sets it in a middleware/`before_action` that has already run.
+
+Rails 8 built-in auth:
+
+```ruby
+config.current_user = lambda do |request|
+  token = request.cookies["session_token"]
+  Session.find_signed(token)&.user if token
+end
+```
+
+### 4. Verify
+
+```bash
+bin/rails routes | grep testimonials     # engine mounted
+bin/rails testimonials:seed_demo         # optional sample data, idempotent
+```
+
+Then, in the running app: load any page and confirm `data-testimonials-config` appears in the HTML source, and that `/testimonials` renders the dashboard in development. The widget stays invisible until opened — an empty-looking page is correct.
+
+### Opening the widget
+
+| Way | Code | Throttled? |
+| --- | --- | --- |
+| Your own button | `<%= testimonials_button %>`, or any element with `data-testimonial-prompt` (`="nps"` for NPS) | No |
+| JavaScript | `window.Testimonials.open()` / `window.Testimonials.openNps()` | No |
+| From a controller, at a success moment | `testimonial_prompt!` / `testimonial_prompt!(:nps)` | Yes |
+
+`testimonial_prompt!` is available in every controller (the engine includes it). It sets a flash and the widget auto-opens on the next rendered page **if** the throttle allows — already submitted, recently dismissed, or prompted `max_prompts` times means it stays shut. Call it liberally; that is the design.
+
+```ruby
+def create
+  # ...
+  testimonial_prompt! if current_user.invoices.count == 10
+  redirect_to invoices_path
+end
+```
+
+**On a `--skip-prompt-events` install `testimonial_prompt!` is a no-op** — with no history there is nothing to throttle with, and a prompt nothing can throttle would reopen on every page. Use an explicit opener instead, or add the ledger (see below).
+
+### Rendering what was collected
+
+The gem ships **no display UI** on purpose, and its own views are for the dashboard and the public pages only. Render approved testimonials with the host app's own markup:
+
+```ruby
+Testimonials::Testimonial.publishable.featured_first.limit(6)   # approved + publicly consented
+Testimonials::Testimonial.publishable.for_tenant(key)           # multi-tenant
+Testimonials::NpsResponse.score                                 # −100..100
+```
+
+`examples/` in the gem has copy-paste starting points: `wall_of_love.html.erb`, `testimonial_card.html.erb`, `badge.html.erb`, `json_ld.html.erb` (schema.org), `static_site.md`. Prefer adapting one over inventing a layout.
+
+There is also a read API — `GET /testimonials/api/testimonials` (filters: `featured=1`, `min_rating=4`, `kind=video`, `limit=12`) and `GET /testimonials/api/stats`. Admin-only unless `config.public_api = true`. Emails and author ids are never serialized.
+
+### Adding a skipped feature later
+
+Order matters: **migrate first, then flip the flag.** The flag is what the code checks, so setting it before the table exists is the one broken state.
+
+```bash
+bin/rails generate testimonials:nps            # then db:migrate, then config.nps = true
+bin/rails generate testimonials:prompt_events  # then db:migrate, then config.prompt_events = true
+```
+
+Both land on exactly the schema a full install produces, tenant column and indexes included.
+
+### Multi-tenancy
+
+One resolver returning an **opaque key** — GlobalID, id, subdomain, slug. The gem never takes a foreign key into host models:
+
+```ruby
+config.tenant = ->(request) { Current.organization&.to_gid&.to_s }
+```
+
+Optional sugar on a host model (`has_testimonials` is available on every Active Record class already):
+
+```ruby
+class Organization < ApplicationRecord
+  has_testimonials   # keyed by to_gid.to_s — must match config.tenant
+end
+organization.testimonials.approved
+```
+
+`bin/rails generate testimonials:tenant` exists **only** to add the `tenant` column to installs made before it existed. A fresh install already has it, and running that generator will fail on a duplicate column. Do not run it as part of a new install.
+
+### Do not
+
+- **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 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.
+
+### Configuration worth knowing
+
+Everything is optional; a fresh install works with zero config. Full list with comments is in the generated initializer.
+
+| Option | Default | Note |
+| --- | --- | --- |
+| `authorize_admin` | development only | **Set before deploying.** |
+| `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. |
+| `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. |
+| `public_api` | `false` | Serves the read API without auth, CORS `*`. |
+| `on_submit`, `on_detractor` | no-ops | Run inline after save — keep fast or enqueue a job. |
+| `mount_path` | `"/testimonials"` | Must match `mount_testimonials at:` in routes. |
+| `rate_limit` | `{ to: 5, within: 60 }` | Rails 7.2+; ignored on 7.1. `nil` disables. |
+
+Turbo Drive and nonce-based CSP work out of the box; the widget config rides in a `type="application/json"` block (data, not code) and the code is a same-origin `src` script. 26 locales ship with the gem, including localized guiding questions.
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| `/testimonials` returns 403 "Set Testimonials.config.authorize_admin to grant access" | Exactly what it says: still at the development-only default. |
+| Widget never appears | `testimonials_tag` missing from the rendered layout, or `config.enabled` returning false. |
+| `testimonial_prompt!` never opens anything | `config.prompt_events` is false, or the user is throttled (submitted / dismissed recently / hit `max_prompts`). |
+| `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`. |
+| `undefined local variable current_user` in the initializer | A gate lambda treated its argument as a controller. It is a `request`. |
+
+---
+
+## Working on the gem itself
+
+```bash
+bundle exec rake test            # minitest, dummy app under test/dummy
+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/
+```
+
+Layout: `app/` controllers, models, dashboard views · `lib/testimonials/` config, widget JS/CSS, seeds, engine · `lib/generators/testimonials/` install, nps, prompt_events, tenant · `config/locales/` 26 locales · `test/` minitest, `test/dummy` the host app · `examples/` display snippets for hosts.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Optional features are guarded by a config flag, never by schema introspection.** `--skip-nps` and `--skip-prompt-events` leave tables out; nothing may ask the database whether a table exists, and nothing may touch the database at boot. Guard at the entry points (one `before_action`, one model class method) so the flag is checked once, not at six call sites.
+- **Every install shape gets a test that drops the table for real** (`test/integration/skip_nps_test.rb`, `skip_prompt_events_test.rb`), so a slipped guard raises `no such table` instead of passing quietly. Generator tests pin each migration and initializer shape and check the ERB still compiles as Ruby.
+- **The widget is plain ES5-style JS in `lib/testimonials/widget.js`**, served by the engine, no build step, no framework. It reads its config from a JSON block on every `turbo:load`.
+- **Display stays headless.** New display UI belongs in `examples/`, not in `app/views`.
+- Every user-facing change bumps `lib/testimonials/version.rb` and adds a `CHANGELOG.md` entry that says what it costs, not only what it adds.
+- Commit messages are prose that explains the tradeoff — read `git log` before writing one.

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 0.7.10
+
+- The prompt-history ledger is now optional too. `bin/rails generate
+  testimonials:install --skip-prompt-events` leaves out the
+  `testimonials_prompt_events` table and writes `config.prompt_events = false`,
+  for apps that open the widget from their own button. `bin/rails generate
+  testimonials:prompt_events` adds the table later, like `testimonials:nps`.
+- With the flag off **nothing auto-opens**: `testimonial_prompt!` is a no-op,
+  because the history exists only to throttle auto-prompts and a prompt nothing
+  can throttle would reopen on every page. Explicit opens
+  (`data-testimonial-prompt`, `window.Testimonials.open()`), both public pages,
+  the dashboard and every submission path work unchanged.
+- `POST /testimonials/events` is refused when the flag is off, and the widget
+  stops posting shown/dismissed at all (`promptEvents.enabled` in its config).
+- `testimonials:seed_demo` skips the demo prompt history when the ledger is
+  off, and the `testimonials:tenant` migration skips either optional table when
+  it isn't there.
+- Adds `AGENTS.md`: install and integration instructions written for coding
+  agents, covering the request-shaped config lambdas, both skip flags, and the
+  mistakes agents actually make. It ships inside the gem, so
+  `cat "$(bundle show testimonials)/AGENTS.md"` works from a host app —
+  `examples/` now ships for the same reason.
+
+## 0.7.9
+
+- NPS is now optional at install time. `bin/rails generate testimonials:install
+  --skip-nps` leaves out the `testimonials_nps_responses` table and writes
+  `config.nps = false`, so an app that only wants testimonials carries neither
+  the table nor the NPS tab. `bin/rails generate testimonials:nps` adds the
+  table later, mirroring the `testimonials:tenant` upgrade path.
+- The guard is `config.nps`, not table introspection — nothing checks the
+  schema at runtime and nothing touches the database at boot. Consequently
+  `/testimonials/nps_responses` now 404s when `config.nps` is false instead of
+  still serving history; flip the flag back to read old responses. The
+  dashboard nav already hid the tab, so only a typed URL reached it.
+- `testimonials:seed_demo` skips NPS rows when the flow is off, and the
+  `testimonials:tenant` migration skips the NPS table when it isn't there.
+
 ## 0.7.8
 
 - The NPS dashboard now says what the score means. The card carries the band

data/README.md

@@ -33,6 +33,24 @@ bin/rails db:migrate
 The generator writes the initializer, the migration, and mounts the engine at
 `/testimonials`. Nothing renders until the widget is opened.
 
+Two parts are optional at install time, and skipping either leaves out its
+table:
+
+```bash
+bin/rails generate testimonials:install --skip-nps            # no NPS at all
+bin/rails generate testimonials:install --skip-prompt-events  # no auto-prompts
+```
+
+`--skip-nps` drops the 0–10 survey: no table, no dashboard tab, no prompt.
+`--skip-prompt-events` drops the prompt history — for apps that open the widget
+from their own button and never call `testimonial_prompt!`, since that history
+exists only to throttle auto-prompts. See
+[Prompting users](#prompting-users) for what changes.
+
+Changed your mind later: `bin/rails generate testimonials:nps` or
+`bin/rails generate testimonials:prompt_events`, migrate, and set the matching
+flag (`config.nps`, `config.prompt_events`) to `true`.
+
 Optional demo data:
 
 ```bash
@@ -50,6 +68,11 @@ refreshes those records instead of duplicating them.
 
 Ruby >= 3.2 · Rails >= 7.1 · 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
+and the things it should not do. It ships inside the gem, so
+`cat "$(bundle show testimonials)/AGENTS.md"` works from any app that bundles it.
+
 ## What you get
 
 |                 |                                                                         |
@@ -123,6 +146,15 @@ The widget auto-opens on the next rendered page **if** the throttle allows:
 `data-testimonial-prompt` (or `="nps"`), or `window.Testimonials.open()` /
 `window.Testimonials.openNps()`.
 
+That history lives in `testimonials_prompt_events`, one row per shown,
+dismissed or submitted, and it is optional. `config.prompt_events = false` —
+what `--skip-prompt-events` writes at install — keeps no history at all, and so
+**nothing auto-opens**: `testimonial_prompt!` becomes a no-op, because a prompt
+nothing can throttle would reopen on every page. Explicit opens, the public
+pages, and everything above them are untouched, so an app that opens the widget
+from its own button loses nothing. Want auto-prompts back:
+`bin/rails generate testimonials:prompt_events`, migrate, flip the flag.
+
 ## Configure
 
 Everything is optional — a fresh install works with zero config. In
@@ -146,6 +178,7 @@ Everything is optional — a fresh install works with zero config. In
 | `storage_service` | app default | Active Storage service for uploads (a `storage.yml` key) |
 | `reprompt_after` | `90.days` | Cooldown after a dismissal |
 | `max_prompts` | `3` | Lifetime auto-prompt cap per user |
+| `prompt_events` | `true` | The prompt history the throttle reads. `false` = no history, no auto-prompts |
 | `public_collection` | `true` | The shareable `/testimonials/new` and `/testimonials/nps/new` pages |
 | `public_api` | `false` | Serve the read API without auth (CORS `*`) |
 | `nps` | `true` | The 0–10 NPS flow |
@@ -242,16 +275,29 @@ throttle would allow it. Detractors (0–6) trigger `on_detractor`, which pairs
 well with [ideasbugs](https://github.com/yshmarov/ideasbugs). Your score and
 every response live at `/testimonials/nps_responses`.
 
+| 1. One question, eleven taps | 2. The reason, optional |
+| --- | --- |
+| ![The NPS prompt: how likely are you to recommend us, scored 0 to 10](https://raw.githubusercontent.com/yshmarov/testimonials/main/docs/screenshots/nps-01-score.jpg) | ![The follow-up asking for the main reason behind the score](https://raw.githubusercontent.com/yshmarov/testimonials/main/docs/screenshots/nps-02-comment.png) |
+| Ten seconds of work, and "Not now" is always there. | The comment is where the actionable half lives. Promoters go straight on to the testimonial form. |
+
 The score is `% promoters − % detractors`, from −100 to +100, and the dashboard
 reads it against the usual benchmarks so nobody has to go and google them:
 below 0 needs work, 0–29 is good, 30–69 is great, 70 and up is world-class. A
 scale under the number shows where you sit, and under 30 responses the card
 says the sample is too thin to read much into.
 
+<img src="https://raw.githubusercontent.com/yshmarov/testimonials/main/docs/screenshots/nps-dashboard.jpg" alt="The NPS dashboard: a score of 41 badged Great, a scale marking where it sits between −100 and +100, promoter/passive/detractor counts, and the collapsed panel explaining the formula and the benchmarks" width="820">
+
 `/testimonials/nps/new` is the same question on its own page — the link for an
 email campaign, where there is no app session to prompt inside of. A promoter
 who scores 9–10 gets the testimonial form right there on the page.
 
+NPS is optional. `config.nps = false` — what `--skip-nps` writes at install —
+turns off the prompt, the public page, the `/api/stats` score and the dashboard
+tab, and `/testimonials/nps_responses` then 404s. Turning it off on an install
+that has the table hides existing responses along with everything else; flip it
+back to read them.
+
 ## The public pages
 
 Two standalone, self-styled pages for people outside the app — drop either link

data/app/controllers/testimonials/events_controller.rb

@@ -10,6 +10,9 @@ module Testimonials
     CLIENT_ACTIONS = %w[shown dismissed].freeze
 
     before_action :require_enabled
+    # An install run with --skip-prompt-events has no ledger to write to, and
+    # the widget it serves knows not to post here in the first place.
+    before_action :require_prompt_events
 
     def create
       kind = params[:kind].to_s
@@ -21,5 +24,11 @@ module Testimonials
                           author_id: current_author_id, visitor_token: ensure_visitor_token)
       head :no_content
     end
+
+    private
+
+    def require_prompt_events
+      head :forbidden unless Testimonials.config.prompt_events
+    end
   end
 end

data/app/controllers/testimonials/nps_responses_controller.rb

@@ -8,6 +8,9 @@ module Testimonials
     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
     before_action :set_response, only: :show
 
     def index
@@ -31,6 +34,10 @@ module Testimonials
 
     private
 
+    def require_nps
+      head :not_found unless Testimonials.config.nps
+    end
+
     def set_response
       @response = NpsResponse.for_tenant(current_tenant).find(params[:id])
     end

data/app/helpers/testimonials/widget_helper.rb

@@ -72,6 +72,10 @@ module Testimonials
       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
       return unless Testimonials::PromptEvent.eligible?(

data/app/models/testimonials/prompt_event.rb

@@ -12,6 +12,12 @@ module Testimonials
   #   * shown max_prompts times     -> never auto-prompted for that kind again
   #
   # Explicit opens (the user clicked something) bypass all of this.
+  #
+  # The ledger is optional: an install run with --skip-prompt-events has no
+  # table behind this class and config.prompt_events is false, so record! is a
+  # no-op and eligible? answers without a query. Every write and every read
+  # goes through the two methods below, so that flag is the only guard needed
+  # — nothing here asks the schema at runtime.
   class PromptEvent < ApplicationRecord
     KINDS = %w[testimonial nps].freeze
     ACTIONS = %w[shown dismissed submitted].freeze
@@ -21,6 +27,7 @@ module Testimonials
 
     class << self
       def record!(kind:, action:, author_id: nil, visitor_token: nil, tenant: nil)
+        return unless Testimonials.config.prompt_events
         return if author_id.blank? && visitor_token.blank?
 
         create!(kind: kind.to_s, action: action.to_s, tenant: tenant.presence,
@@ -34,6 +41,11 @@ module Testimonials
         return false unless KINDS.include?(kind)
         # No identity, no history: a brand-new visitor is always eligible.
         return true if author_id.blank? && visitor_token.blank?
+        # No ledger, no history either — the same answer, one flag earlier.
+        # This is not a licence to nag: with the ledger off nothing auto-opens
+        # (see WidgetHelper#testimonials_auto_open), and the one caller left is
+        # the promoter offered the form inside a flow they opened themselves.
+        return true unless Testimonials.config.prompt_events
 
         history = subject(author_id, visitor_token, tenant).where(kind: kind)
         config = Testimonials.config

data/app/views/testimonials/nps_responses/index.html.erb

@@ -2,10 +2,10 @@
 
 <div class="page-head">
   <h1><%= t('testimonials.dashboard.nps', default: 'NPS') %></h1>
-  <%# The shareable NPS page, same idea as the testimonial one. This dashboard
-      still reads history when config.nps is off, but that page 404s — so the
-      link needs both switches. %>
-  <% if Testimonials.config.public_collection && Testimonials.config.nps %>
+  <%# The shareable NPS page, same idea as the testimonial one. config.nps is
+      already true here — the controller 404s otherwise — so only the public
+      switch is left to check. %>
+  <% if Testimonials.config.public_collection %>
     <a class="button share-link" href="<%= nps_collection_url %>" target="_blank" rel="noopener"
        title="<%= nps_collection_url %>">
       🔗 <%= t('testimonials.dashboard.nps_page', default: 'Ask for NPS scores') %>

data/examples/README.md

@@ -0,0 +1,17 @@
+# Display examples
+
+testimonials deliberately ships **no display UI** — approved testimonials are
+yours to render, via `Testimonials::Testimonial.publishable` inside the app or
+via the JSON API anywhere else. These files are copy-paste starting points so
+you can see the end result in minutes. Take them, restyle them, own them.
+
+| File | What it renders |
+| --- | --- |
+| [`wall_of_love.html.erb`](wall_of_love.html.erb) | A responsive grid of text + video testimonials |
+| [`testimonial_card.html.erb`](testimonial_card.html.erb) | A single quote card for a landing/pricing page |
+| [`badge.html.erb`](badge.html.erb) | The "★ 4.9 from 87 reviews" chip |
+| [`json_ld.html.erb`](json_ld.html.erb) | schema.org AggregateRating + Review markup for Google rich snippets |
+| [`static_site.md`](static_site.md) | Rendering testimonials on a separate marketing site (Astro & friends) from the public API |
+
+In-app examples read the models directly — no HTTP, no `public_api` needed.
+The static-site example is the one place the public API earns its keep.

data/examples/badge.html.erb

@@ -0,0 +1,13 @@
+<%# The "★ 4.9 from 87 reviews" chip. Same numbers the API's /api/stats serves. %>
+
+<% scope = Testimonials::Testimonial.publishable.where.not(rating: nil) %>
+<% if (count = scope.count).positive? %>
+  <a href="#wall-of-love"
+     style="display: inline-flex; align-items: center; gap: 6px; padding: 6px 14px;
+            border: 1px solid #e5e7eb; border-radius: 999px; text-decoration: none;
+            font: 600 14px system-ui, sans-serif; color: inherit;">
+    <span style="color: #f59e0b;">★</span>
+    <%= scope.average(:rating).to_f.round(1) %>
+    <span style="font-weight: 400; color: #6b7280;">from <%= count %> reviews</span>
+  </a>
+<% end %>

data/examples/json_ld.html.erb

@@ -0,0 +1,28 @@
+<%# schema.org structured data for Google rich snippets (star ratings in
+    search results). Put it in the <head> of the page that shows the reviews. %>
+
+<% scope = Testimonials::Testimonial.publishable %>
+<% rated = scope.where.not(rating: nil) %>
+<% if rated.exists? %>
+  <script type="application/ld+json">
+    <%= raw({
+          '@context' => 'https://schema.org',
+          '@type' => 'Product',
+          name: Testimonials.app_name,
+          aggregateRating: {
+            '@type' => 'AggregateRating',
+            ratingValue: rated.average(:rating).to_f.round(2),
+            reviewCount: rated.count
+          },
+          review: scope.featured_first.limit(5).map do |testimonial|
+            {
+              '@type' => 'Review',
+              reviewBody: testimonial.quote,
+              author: { '@type' => 'Person', name: testimonial.name },
+              reviewRating: testimonial.rating &&
+                { '@type' => 'Rating', ratingValue: testimonial.rating }
+            }.compact
+          end
+        }.to_json) %>
+  </script>
+<% end %>

data/examples/static_site.md

@@ -0,0 +1,43 @@
+# Testimonials on a separate marketing site
+
+Your Rails app collects and curates; your marketing site (Astro, Eleventy,
+plain HTML on Cloudflare — anything) renders. Turn on the public API:
+
+```ruby
+# config/initializers/testimonials.rb
+config.public_api = true
+```
+
+`GET https://app.example.com/testimonials/api/testimonials` now serves approved +
+consented records to anyone (CORS `*`), and `/testimonials/api/stats` serves the
+badge numbers. Emails are never included.
+
+## Astro example (build-time fetch)
+
+```astro
+---
+const res = await fetch("https://app.example.com/testimonials/api/testimonials?limit=12");
+const { testimonials } = await res.json();
+const stats = await (await fetch("https://app.example.com/testimonials/api/stats")).json();
+---
+
+<p>★ {stats.average_rating} from {stats.count} reviews</p>
+
+<div class="wall">
+  {testimonials.map((t) => (
+    <figure>
+      {t.rating && <div>{"★".repeat(t.rating)}</div>}
+      {t.video_url && <video controls preload="metadata" poster={t.poster_url} src={t.video_url}></video>}
+      {t.quote && <blockquote>“{t.quote}”</blockquote>}
+      <figcaption>
+        {t.avatar_url && <img src={t.avatar_url} alt="" width="36" height="36" />}
+        <b>{t.name}</b> {t.title_company && <span>— {t.title_company}</span>}
+      </figcaption>
+    </figure>
+  ))}
+</div>
+```
+
+Media URLs (`video_url`, `avatar_url`) point back at the Rails app, which
+redirects to signed Active Storage URLs with Range support — videos play
+directly in a `<video>` tag.

data/examples/testimonial_card.html.erb

@@ -0,0 +1,17 @@
+<%# One hero quote for a pricing or landing page. Pick it explicitly, or take
+    the newest featured one as below. %>
+
+<% testimonial = Testimonials::Testimonial.publishable.where(featured: true).newest_first.first %>
+<% if testimonial %>
+  <figure style="max-width: 560px; margin: 0 auto; padding: 24px; border: 1px solid #e5e7eb;
+                 border-radius: 16px; font: 17px/1.6 system-ui, sans-serif; text-align: center;">
+    <% if testimonial.rating %>
+      <div style="color: #f59e0b; letter-spacing: 3px; margin-bottom: 8px;"><%= '★' * testimonial.rating %></div>
+    <% end %>
+    <blockquote style="margin: 0 0 16px; font-weight: 500;">“<%= testimonial.quote %>”</blockquote>
+    <figcaption style="font-size: 14px; color: #6b7280;">
+      <b style="color: inherit;"><%= testimonial.name %></b>
+      <% if testimonial.title_company.present? %> — <%= testimonial.title_company %><% end %>
+    </figcaption>
+  </figure>
+<% end %>

data/examples/wall_of_love.html.erb

@@ -0,0 +1,43 @@
+<%# A wall of love: drop into any view of the host app and restyle at will.
+    Videos stream through the engine's gated media route (admin, or
+    public_api + publishable). %>
+
+<style>
+  .wall { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 16px; }
+  .wall-card { border: 1px solid #e5e7eb; border-radius: 14px; padding: 18px; background: #fff;
+               font: 15px/1.5 system-ui, sans-serif; break-inside: avoid; }
+  .wall-stars { color: #f59e0b; letter-spacing: 2px; margin-bottom: 6px; }
+  .wall-quote { margin: 0 0 12px; }
+  .wall-author { display: flex; align-items: center; gap: 10px; }
+  .wall-author img { width: 36px; height: 36px; border-radius: 50%; object-fit: cover; }
+  .wall-author b { display: block; font-size: 14px; }
+  .wall-author span { font-size: 13px; color: #6b7280; }
+  .wall-card video { width: 100%; border-radius: 10px; background: #000; margin-bottom: 10px; }
+</style>
+
+<div class="wall">
+  <% Testimonials::Testimonial.publishable.featured_first.limit(12).each do |testimonial| %>
+    <figure class="wall-card">
+      <% if testimonial.rating %>
+        <div class="wall-stars"><%= '★' * testimonial.rating %></div>
+      <% end %>
+      <% if testimonial.video_attached? %>
+        <video controls preload="metadata"
+               poster="<%= testimonials.testimonial_poster_path(testimonial) if testimonial.poster_attached? %>"
+               src="<%= testimonials.testimonial_video_path(testimonial) %>"></video>
+      <% end %>
+      <% if testimonial.quote.present? %>
+        <blockquote class="wall-quote">“<%= testimonial.quote %>”</blockquote>
+      <% end %>
+      <figcaption class="wall-author">
+        <% if testimonial.avatar_attached? %>
+          <img src="<%= testimonials.testimonial_avatar_path(testimonial) %>" alt="">
+        <% end %>
+        <div>
+          <b><%= testimonial.name %></b>
+          <span><%= testimonial.title_company %></span>
+        </div>
+      </figcaption>
+    </figure>
+  <% end %>
+</div>

data/lib/generators/testimonials/install/install_generator.rb

@@ -12,8 +12,24 @@ module Testimonials
 
       desc 'Installs testimonials: config initializer, migration, and engine mount.'
 
+      # Two parts of the gem an app can genuinely not want. Skipping either
+      # leaves out its table and writes the matching config flag as false, so
+      # nothing ever reaches a table that isn't there — no runtime
+      # introspection, no boot-time database call. `testimonials:nps` and
+      # `testimonials:prompt_events` add them later.
+      class_option :skip_nps, type: :boolean, default: false,
+                              desc: 'Leave out the NPS table and turn the NPS flow off'
+
+      # The throttle ledger only earns its rows if the app auto-prompts. An
+      # app that opens the widget from its own button writes one row per
+      # dismissal for nothing, so it can leave the table out — and then
+      # testimonial_prompt! no longer auto-opens, since nothing could throttle
+      # it. Explicit opens are unaffected.
+      class_option :skip_prompt_events, type: :boolean, default: false,
+                                        desc: 'Leave out the prompt-history table; no auto-prompts, only explicit opens'
+
       def create_initializer
-        copy_file 'initializer.rb', 'config/initializers/testimonials.rb'
+        template 'initializer.rb.tt', 'config/initializers/testimonials.rb'
       end
 
       def create_migration_file
@@ -29,8 +45,19 @@ module Testimonials
         say "\ntestimonials installed. Run `rails db:migrate`, then add", :green
         say '`<%= testimonials_tag %>` before </body> in your layout.'
         say 'Triage testimonials at /testimonials (development only until you set config.authorize_admin).'
-        say 'Optional: run `bin/rails testimonials:seed_demo` for sample testimonials and NPS.'
+        samples = options[:skip_nps] ? 'testimonials' : 'testimonials and NPS'
+        say "Optional: run `bin/rails testimonials:seed_demo` for sample #{samples}."
         say "Collect from outside the app via /testimonials/new.\n"
+
+        if options[:skip_nps]
+          say 'Installed without NPS. Add it later with `bin/rails generate testimonials:nps`.', :yellow
+        end
+
+        return unless options[:skip_prompt_events]
+
+        say 'Installed without prompt history, so testimonial_prompt! will not auto-open the ' \
+            'widget — open it from your own button. Add it later with ' \
+            '`bin/rails generate testimonials:prompt_events`.', :yellow
       end
 
       private

data/lib/generators/testimonials/install/templates/create_testimonials_tables.rb.tt

@@ -26,6 +26,7 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
     add_index :testimonials_testimonials, :status
     add_index :testimonials_testimonials, %i[tenant status]
     add_index :testimonials_testimonials, %i[tenant status consent_given]
+<% unless options[:skip_nps] -%>
 
     create_table :testimonials_nps_responses do |t|
       t.integer :score, null: false
@@ -41,6 +42,8 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
       t.timestamps
     end
     add_index :testimonials_nps_responses, %i[tenant score]
+<% end -%>
+<% unless options[:skip_prompt_events] -%>
 
     create_table :testimonials_prompt_events do |t|
       t.string :kind, null: false
@@ -53,5 +56,6 @@ class CreateTestimonialsTables < ActiveRecord::Migration<%= migration_version %>
     end
     add_index :testimonials_prompt_events, %i[tenant author_id kind]
     add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
+<% end -%>
   end
 end

data/lib/generators/testimonials/install/templates/{initializer.rb → initializer.rb.tt}

@@ -69,6 +69,21 @@ Testimonials.configure do |config|
   # config.reprompt_after = 90.days
   # config.max_prompts = 3
 
+  # The prompt history the throttle reads (testimonials_prompt_events).
+<% if options[:skip_prompt_events] -%>
+  # Installed with --skip-prompt-events, so there is no table and no history is
+  # written. Nothing is throttled, so nothing auto-opens either:
+  # testimonial_prompt! is a no-op here and the widget opens from your own
+  # button, data-testimonial-prompt, or window.Testimonials.open(). To turn
+  # auto-prompts on later: `bin/rails generate testimonials:prompt_events &&
+  # bin/rails db:migrate`, then flip this to true.
+  config.prompt_events = false
+<% else -%>
+  # False keeps no history — and then nothing auto-opens, since nothing could
+  # throttle it. For apps that only open the widget on a click.
+  # config.prompt_events = true
+<% end -%>
+
   # The public-use consent line, stored verbatim when a customer picks
   # "use publicly". nil = localized default ("You can use my testimonial
   # publicly in your marketing and sales."). The private-use line is
@@ -84,7 +99,15 @@ Testimonials.configure do |config|
   # config.public_api = false
 
   # NPS surveys. Promoters (9–10) are offered the testimonial form right away.
+<% if options[:skip_nps] -%>
+  # Installed with --skip-nps, so there is no testimonials_nps_responses table
+  # and the NPS flow, dashboard tab and public page stay off. To add it later:
+  # `bin/rails generate testimonials:nps && bin/rails db:migrate`, then flip
+  # this to true.
+  config.nps = false
+<% else -%>
   # config.nps = true
+<% end -%>
   # config.nps_reprompt_after = 90.days
 
   # Called with each saved Testimonial or NpsResponse — notify Slack, email…

data/lib/generators/testimonials/nps/nps_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Testimonials
+  module Generators
+    # For apps that installed with --skip-nps and later want the 0–10 survey:
+    # creates the testimonials_nps_responses table. A full install already has
+    # it. Additive and safe — nothing reads the table until config.nps is true.
+    #
+    #   bin/rails generate testimonials:nps && bin/rails db:migrate
+    class NpsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Adds the NPS responses table for an install that skipped it.'
+
+      def create_migration_file
+        migration_template 'create_testimonials_nps_responses.rb.tt',
+                           'db/migrate/create_testimonials_nps_responses.rb'
+      end
+
+      def post_install
+        say "\nNPS table queued. Run `rails db:migrate`, then set", :green
+        say 'config.nps = true in config/initializers/testimonials.rb to turn the flow on.'
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/testimonials/nps/templates/create_testimonials_nps_responses.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateTestimonialsNpsResponses < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :testimonials_nps_responses do |t|
+      t.integer :score, null: false
+      t.text :comment
+      t.string :author_id
+      t.string :name
+      t.string :email
+      t.string :page_url
+      t.string :user_agent
+      t.string :locale
+      t.string :tenant # opaque per-tenant key; nil = single global collection
+
+      t.timestamps
+    end
+    add_index :testimonials_nps_responses, %i[tenant score]
+  end
+end

data/lib/generators/testimonials/prompt_events/prompt_events_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Testimonials
+  module Generators
+    # For apps that installed with --skip-prompt-events and later want
+    # auto-prompts: creates the testimonials_prompt_events table, the ledger
+    # the throttle reads. A full install already has it. Additive and safe —
+    # nothing reads or writes the table until config.prompt_events is true.
+    #
+    #   bin/rails generate testimonials:prompt_events && bin/rails db:migrate
+    class PromptEventsGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Adds the prompt history table for an install that skipped it.'
+
+      def create_migration_file
+        migration_template 'create_testimonials_prompt_events.rb.tt',
+                           'db/migrate/create_testimonials_prompt_events.rb'
+      end
+
+      def post_install
+        say "\nPrompt history table queued. Run `rails db:migrate`, then set", :green
+        say 'config.prompt_events = true in config/initializers/testimonials.rb to let'
+        say 'testimonial_prompt! auto-open the widget again.'
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/testimonials/prompt_events/templates/create_testimonials_prompt_events.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreateTestimonialsPromptEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :testimonials_prompt_events do |t|
+      t.string :kind, null: false
+      t.string :action, null: false
+      t.string :author_id
+      t.string :visitor_token
+      t.string :tenant # opaque per-tenant key; nil = single global collection
+
+      t.timestamps
+    end
+    add_index :testimonials_prompt_events, %i[tenant author_id kind]
+    add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
+  end
+end

data/lib/generators/testimonials/tenant/templates/add_tenant_to_testimonials.rb.tt

@@ -3,12 +3,19 @@
 class AddTenantToTestimonials < ActiveRecord::Migration<%= migration_version %>
   def change
     add_column :testimonials_testimonials, :tenant, :string
-    add_column :testimonials_nps_responses, :tenant, :string
-    add_column :testimonials_prompt_events, :tenant, :string
-
     add_index :testimonials_testimonials, %i[tenant status]
     add_index :testimonials_testimonials, %i[tenant status consent_given]
-    add_index :testimonials_nps_responses, %i[tenant score]
+
+    # The optional tables: an install run with --skip-nps or
+    # --skip-prompt-events has no table to add the column to.
+    if table_exists?(:testimonials_nps_responses)
+      add_column :testimonials_nps_responses, :tenant, :string
+      add_index :testimonials_nps_responses, %i[tenant score]
+    end
+
+    return unless table_exists?(:testimonials_prompt_events)
+
+    add_column :testimonials_prompt_events, :tenant, :string
     add_index :testimonials_prompt_events, %i[tenant author_id kind]
     add_index :testimonials_prompt_events, %i[tenant visitor_token kind]
   end

data/lib/testimonials/configuration.rb

@@ -69,6 +69,15 @@ module Testimonials
     # (clicking your link) always work.
     attr_accessor :reprompt_after, :max_prompts
 
+    # The throttling ledger itself (testimonials_prompt_events). Off means no
+    # per-user prompt history is written — and therefore no auto-prompts:
+    # `testimonial_prompt!` stops opening the widget, because a prompt that
+    # can't be throttled would reopen on every page. Explicit opens — your
+    # own button, `data-testimonial-prompt`, `window.Testimonials.open()`,
+    # the public pages — are unaffected. For apps that only ever open the
+    # widget on a click; `--skip-prompt-events` writes it at install time.
+    attr_accessor :prompt_events
+
     # Consent line stored verbatim with each submission. nil uses the
     # localized default.
     attr_accessor :consent_text
@@ -123,6 +132,7 @@ module Testimonials
       @storage_service = nil
       @reprompt_after = 90 * 24 * 60 * 60
       @max_prompts = 3
+      @prompt_events = true
       @consent_text = nil
       @public_collection = true
       @public_api = false

data/lib/testimonials/prompt_helper.rb

@@ -7,6 +7,10 @@ module Testimonials
   # throttle allows, so calling this liberally is safe: users who submitted,
   # recently dismissed, or were already prompted max_prompts times are left
   # alone.
+  #
+  # An install with `config.prompt_events = false` keeps no prompt history, so
+  # there is nothing to throttle with and this is a no-op — that app opens the
+  # widget on a click instead.
   module PromptHelper
     def testimonial_prompt!(kind = :testimonial)
       flash[:testimonials_prompt] = kind.to_s

data/lib/testimonials/seeds.rb

@@ -90,8 +90,10 @@ module Testimonials
     def self.load!(tenant: nil)
       {
         testimonials: load_testimonials!(tenant: tenant),
-        nps_responses: load_nps_responses!(tenant: tenant),
-        prompt_events: load_prompt_events!(tenant: tenant)
+        # An install run with --skip-nps or --skip-prompt-events has no table
+        # to seed into.
+        nps_responses: (Testimonials.config.nps ? load_nps_responses!(tenant: tenant) : []),
+        prompt_events: (Testimonials.config.prompt_events ? load_prompt_events!(tenant: tenant) : [])
       }
     end
 

data/lib/testimonials/version.rb

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

data/lib/testimonials/widget.js

@@ -14,7 +14,8 @@
  * a star expands into the full form (text or recorded video, consent, guest
  * contact fields). NPS asks 0–10, and promoters are offered the testimonial
  * form right after. Auto-opens report shown/dismissed to the throttle
- * ledger; explicit opens don't.
+ * ledger; explicit opens don't, and an install without the ledger
+ * (config.promptEvents.enabled false) reports nothing at all.
  *
  * On the public standalone pages the same code renders inline into
  * <div data-testimonials-inline>: the testimonial form (config.mode ===
@@ -1054,6 +1055,8 @@
   }
 
   function postEvent(kind, action) {
+    // No ledger on this install (--skip-prompt-events): nothing to report to.
+    if (!config.promptEvents || !config.promptEvents.enabled) return;
     var data = new FormData();
     data.append("kind", kind);
     data.append("event_action", action);

data/lib/testimonials/widget.rb

@@ -107,6 +107,9 @@ module Testimonials
             maxSize: config.max_avatar_size.to_i
           },
           nps: { enabled: config.nps ? true : false },
+          # The throttle ledger. Off, and the widget skips the shown/dismissed
+          # posts: the endpoint would only refuse them.
+          promptEvents: { enabled: config.prompt_events ? true : false },
           labels: labels
         }
         # Escape "</" so a value can't close the <script> block early.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: testimonials
 version: !ruby/object:Gem::Version
-  version: 0.7.8
+  version: 0.7.10
 platform: ruby
 authors:
 - Yaroslav Shmarov
@@ -38,6 +38,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
@@ -95,9 +96,19 @@ files:
 - config/locales/testimonials.vi.yml
 - config/locales/testimonials.zh-CN.yml
 - config/routes.rb
+- examples/README.md
+- examples/badge.html.erb
+- examples/json_ld.html.erb
+- examples/static_site.md
+- examples/testimonial_card.html.erb
+- examples/wall_of_love.html.erb
 - lib/generators/testimonials/install/install_generator.rb
 - lib/generators/testimonials/install/templates/create_testimonials_tables.rb.tt
-- lib/generators/testimonials/install/templates/initializer.rb
+- lib/generators/testimonials/install/templates/initializer.rb.tt
+- lib/generators/testimonials/nps/nps_generator.rb
+- lib/generators/testimonials/nps/templates/create_testimonials_nps_responses.rb.tt
+- lib/generators/testimonials/prompt_events/prompt_events_generator.rb
+- lib/generators/testimonials/prompt_events/templates/create_testimonials_prompt_events.rb.tt
 - lib/generators/testimonials/tenant/templates/add_tenant_to_testimonials.rb.tt
 - lib/generators/testimonials/tenant/tenant_generator.rb
 - lib/tasks/testimonials_tasks.rake