testimonials 0.1.0

data/lib/generators/testimonials/install/templates/initializer.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+Testimonials.configure do |config|
+  # Shown in the widget ("Enjoying %{app}?") and interpolated into the
+  # default questions. Defaults to your Rails application name.
+  # config.app_name = "My App"
+
+  # Who sees the widget and can submit. Return false to hide and reject for
+  # this request. Defaults to everyone.
+  # config.enabled = ->(request) { true }
+
+  # Who can triage testimonials at the mount path. Defaults to development
+  # only — override before deploying.
+  # config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+
+  # Attribute submissions to a user (optional). Return an object responding
+  # to #id, or nil. Receives the request.
+  # config.current_user = ->(request) { request.env["warden"]&.user }
+
+  # Attribution stored with a signed-in user's submission.
+  # config.user_display = ->(user) { { name: user.name, email: user.email } }
+
+  # Guiding prompts shown above the message field (not form fields).
+  # Default nil = the gem's built-in localized questions. Override with
+  # literal strings, or a lambda for host-side i18n. [] hides the section.
+  # config.questions = ["How has %{app} helped you?", "What's the best part?"]
+  # config.questions = -> { I18n.t("reviews.questions") }
+
+  # Video testimonials (requires Active Storage).
+  # config.video = true
+  # config.max_video_seconds = 120
+  # config.max_video_size = 50.megabytes
+
+  # Guest headshot upload on the public collection page (requires Active Storage).
+  # config.avatars = true
+  # config.max_avatar_size = 5.megabytes
+
+  # Auto-prompt throttling. Explicit opens (user clicked your link) bypass it.
+  # config.reprompt_after = 90.days
+  # config.max_prompts = 3
+
+  # Consent line stored verbatim with each submission. nil = localized default:
+  # "I give permission to use this testimonial across social channels and
+  # other marketing efforts."
+  # config.consent_text = "..."
+
+  # The standalone collection page at /testimonials/new — share it with customers
+  # outside the app. Set false to disable.
+  # config.public_collection = true
+
+  # Unauthenticated read access to GET /testimonials/api/testimonials and
+  # /testimonials/api/stats (approved + consented records only). Off = admins only.
+  # config.public_api = false
+
+  # NPS surveys. Promoters (9–10) are offered the testimonial form right away.
+  # config.nps = true
+  # config.nps_reprompt_after = 90.days
+
+  # Called with each saved Testimonial or NpsResponse — notify Slack, email…
+  # config.on_submit = ->(record) {}
+
+  # Called with each NPS response scored 0–6.
+  # config.on_detractor = ->(nps) {}
+
+  # Per-IP throttle for public endpoints (Rails 7.2+; ignored on 7.1).
+  # config.rate_limit = { to: 5, within: 1.minute }
+
+  # Keep in sync with the `mount` in config/routes.rb.
+  # config.mount_path = "/testimonials"
+end

data/lib/testimonials/configuration.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Host-tunable settings. Everything has a safe default, so a fresh install
+  # works with zero configuration; the hooks below let an app decide who gets
+  # prompted, who can triage, and how submissions are attributed.
+  class Configuration
+    # Shown in the widget ("Enjoying %{app}?") and interpolated into the
+    # default questions. nil resolves to the Rails application name.
+    attr_accessor :app_name
+
+    # Per-request gate for the widget and the submission endpoints. Return
+    # false to hide the widget and reject submissions for this request.
+    attr_accessor :enabled
+
+    # Per-request gate for the built-in dashboard. Defaults to development
+    # only — override it before deploying, e.g. with an admin check.
+    attr_accessor :authorize_admin
+
+    # Resolve the current user for attribution (optional). Return an object
+    # responding to #id, or nil. Receives the request.
+    attr_accessor :current_user
+
+    # Turn a resolved user into the attribution stored with a submission.
+    # Return a hash with :name, :email, and optionally :title_company.
+    # Receives whatever #current_user returned.
+    attr_accessor :user_display
+
+    # Guiding prompts shown above the message field and while recording —
+    # they fight blank-page paralysis, they are not form fields. nil uses the
+    # gem's built-in localized questions (`testimonials.questions`, with
+    # %{app} interpolated). Override with an array of literal strings, or a
+    # callable for host-side i18n: `-> { I18n.t("myapp.review_questions") }`.
+    # An empty array hides the section.
+    attr_accessor :questions
+
+    # Video testimonials (recording and upload). Requires Active Storage.
+    attr_accessor :video
+    attr_accessor :max_video_seconds, :max_video_size
+
+    # Headshot upload for guests on the public collection page. Requires
+    # Active Storage.
+    attr_accessor :avatars
+    attr_accessor :max_avatar_size
+
+    # Auto-prompt throttling. A user who dismissed the widget is not
+    # auto-prompted again within `reprompt_after`; a user auto-prompted
+    # `max_prompts` times without submitting is never auto-prompted again;
+    # a user who submitted a testimonial is done for good. Explicit opens
+    # (clicking your link) always work.
+    attr_accessor :reprompt_after, :max_prompts
+
+    # Consent line stored verbatim with each submission. nil uses the
+    # localized default.
+    attr_accessor :consent_text
+
+    # The standalone collection page at "#{mount_path}/new" — for links you
+    # send to customers outside the app. ON by default; set false to 404 it.
+    attr_accessor :public_collection
+
+    # Unauthenticated read access to the JSON API (approved + consented
+    # records only). OFF by default: the API then answers only for admins.
+    attr_accessor :public_api
+
+    # NPS surveys ("How likely are you to recommend…", 0–10). Promoters
+    # (9–10) are offered the testimonial form right after scoring.
+    attr_accessor :nps
+    attr_accessor :nps_reprompt_after
+
+    # Called with each saved Testimonials::Testimonial or
+    # Testimonials::NpsResponse — notify Slack, send an email. Runs inline
+    # after save; keep it fast or hand off to a job.
+    attr_accessor :on_submit
+
+    # Called with each NPS response scored 0–6. Route it into your feedback
+    # tool, e.g. create a FeedbackEngine::Feedback from nps.comment.
+    attr_accessor :on_detractor
+
+    # Per-IP throttle for the public endpoints, as keyword arguments for
+    # Rails' rate limiter (Rails 7.2+; ignored on 7.1). Read once when the
+    # controller loads — set it in an initializer. nil disables throttling.
+    attr_accessor :rate_limit
+
+    # Where the engine is mounted. The widget posts to paths under it, so
+    # keep this in sync with the `mount` line in your routes.
+    attr_accessor :mount_path
+
+    def initialize
+      @app_name = nil
+      @enabled = ->(_request) { true }
+      @authorize_admin = ->(_request) { Rails.env.development? }
+      @current_user = ->(_request) {}
+      @user_display = lambda { |user|
+        { name: user.try(:name), email: user.try(:email) }
+      }
+      @questions = nil
+      @video = true
+      @max_video_seconds = 120
+      @max_video_size = 50 * 1024 * 1024
+      @avatars = true
+      @max_avatar_size = 5 * 1024 * 1024
+      @reprompt_after = 90 * 24 * 60 * 60
+      @max_prompts = 3
+      @consent_text = nil
+      @public_collection = true
+      @public_api = false
+      @nps = true
+      @nps_reprompt_after = 90 * 24 * 60 * 60
+      @on_submit = ->(_record) {}
+      @on_detractor = ->(_nps_response) {}
+      @rate_limit = { to: 5, within: 60 }
+      @mount_path = '/testimonials'
+    end
+
+    def testimonials_endpoint = mount_path.chomp('/')
+    def nps_endpoint = "#{mount_path.chomp('/')}/nps"
+    def events_endpoint = "#{mount_path.chomp('/')}/events"
+
+    # Video and avatars need Active Storage — both the config switch and the
+    # host actually having it loaded.
+    def video_enabled?
+      video && defined?(::ActiveStorage) ? true : false
+    end
+
+    def avatars_enabled?
+      avatars && defined?(::ActiveStorage) ? true : false
+    end
+  end
+end

data/lib/testimonials/dashboard.js

@@ -0,0 +1,33 @@
+/*
+ * testimonials dashboard helpers — CSP-safe replacements for inline
+ * handlers, which strict script-src policies (nonce or 'self') block.
+ *
+ * forms with data-confirm ask before submitting; controls with
+ * data-autosubmit submit their form on change. Document-level listeners,
+ * registered once, so Turbo navigations into the dashboard are fine.
+ */
+(function () {
+  "use strict";
+
+  if (window.__testimonialsDashboardLoaded) return;
+  window.__testimonialsDashboardLoaded = true;
+
+  document.addEventListener("submit", function (event) {
+    var form = event.target;
+    var message = form && form.dataset ? form.dataset.confirm : null;
+    if (message && !window.confirm(message)) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  }, true);
+
+  document.addEventListener("change", function (event) {
+    var control = event.target;
+    if (!control || !control.dataset || !control.dataset.autosubmit || !control.form) return;
+    if (control.form.requestSubmit) {
+      control.form.requestSubmit();
+    } else {
+      control.form.submit();
+    }
+  });
+})();

data/lib/testimonials/engine.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Testimonials
+  class Engine < ::Rails::Engine
+    isolate_namespace Testimonials
+
+    initializer 'testimonials.helpers' do
+      ActiveSupport.on_load(:action_view) do
+        include Testimonials::WidgetHelper
+      end
+      ActiveSupport.on_load(:action_controller) do
+        include Testimonials::PromptHelper
+      end
+    end
+  end
+end

data/lib/testimonials/prompt_helper.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Testimonials
+  # Included into the host's controllers. Call `testimonial_prompt!` at your
+  # app's success moments — subscription renewed, tenth invoice sent, big
+  # milestone hit. The widget auto-opens on the next rendered page *if* the
+  # throttle allows, so calling this liberally is safe: users who submitted,
+  # recently dismissed, or were already prompted max_prompts times are left
+  # alone.
+  module PromptHelper
+    def testimonial_prompt!(kind = :testimonial)
+      flash[:testimonials_prompt] = kind.to_s
+    end
+  end
+end

data/lib/testimonials/version.rb

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