testimonials 0.1.0

data/lib/testimonials/widget.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+
+module Testimonials
+  # Serves the self-contained browser widget. The JavaScript is plain ES (no
+  # framework, no build step) and styles itself inline, so it drops into any
+  # Rails app regardless of its CSS or JS setup. It is inlined into the page
+  # rather than served as a separate asset to avoid any dependency on the
+  # host's asset pipeline — and it lives under lib/ (not app/assets/) so a
+  # host that *does* run a pipeline never ingests it either.
+  module Widget
+    SOURCE = File.expand_path('widget.js', __dir__)
+    DASHBOARD_SOURCE = File.expand_path('dashboard.js', __dir__)
+
+    # Right-to-left scripts, so the form renders mirrored for those locales.
+    # Matched on the language subtag, so region variants ("ar-EG") count too.
+    RTL_LANGUAGES = %w[ar arc ckb dv fa ha he ks ku ps sd ug ur yi].freeze
+
+    class << self
+      def javascript
+        @javascript ||= File.read(SOURCE)
+      end
+
+      def dashboard_javascript
+        @dashboard_javascript ||= File.read(DASHBOARD_SOURCE)
+      end
+
+      # Content fingerprints for cache-busting script URLs: a changed file is
+      # a changed URL, so no browser can ever run stale widget code — Safari
+      # has been caught ignoring must-revalidate on same-URL scripts.
+      def fingerprint
+        @fingerprint ||= Digest::MD5.hexdigest(javascript)
+      end
+
+      def dashboard_fingerprint
+        @dashboard_fingerprint ||= Digest::MD5.hexdigest(dashboard_javascript)
+      end
+
+      # The two <script> tags the helper renders.
+      #
+      # The config rides in a `type="application/json"` block: it is *data*,
+      # not code, so the browser never executes it and Turbo never tries to
+      # re-run it on a soft visit — which means it needs no CSP nonce and the
+      # widget can re-read the *current* page's config on every `turbo:load`.
+      #
+      # The code is a same-origin `src` script served by the engine — NOT
+      # inlined. Under a nonce-based CSP, Turbo Drive body swaps re-run body
+      # scripts against the *original* page's CSP header, so a fresh inline
+      # nonce gets refused; a same-origin src is covered by `'self'` on every
+      # visit. `nonce:` is still stamped for hosts whose script-src has no
+      # 'self'; pass nil when the app has no nonce.
+      def snippet(locale:, authenticated:, auto_open: nil, mode: 'widget', existing: nil, nonce: nil)
+        json = config_json(locale:, authenticated:, auto_open:, mode:, existing:)
+        nonce_attr = nonce ? %( nonce="#{nonce}") : ''
+        src = "#{Testimonials.config.mount_path.chomp('/')}/widget.js?v=#{fingerprint}"
+
+        %(<script type="application/json" data-testimonials-config>#{json}</script>) +
+          %(<script src="#{src}" defer#{nonce_attr} data-testimonials-widget></script>)
+      end
+
+      def config_json(locale:, authenticated:, auto_open:, mode:, existing: nil)
+        config = Testimonials.config
+        payload = {
+          endpoints: {
+            testimonials: config.testimonials_endpoint,
+            nps: config.nps_endpoint,
+            events: config.events_endpoint
+          },
+          locale: locale.to_s,
+          rtl: rtl?(locale),
+          authenticated: authenticated ? true : false,
+          autoOpen: auto_open&.to_s,
+          mode: mode.to_s,
+          questions: Testimonials.questions,
+          consent: Testimonials.consent_text,
+          # The signed-in user's current review, if any: the widget opens it
+          # pre-filled for editing instead of starting a second one — rating,
+          # text, consent state, and a playable URL for an attached video.
+          existing: existing && {
+            rating: existing.rating,
+            body: existing.body,
+            consent: existing.consent_given ? true : false,
+            videoUrl: existing_video_url(existing)
+          },
+          video: {
+            enabled: config.video_enabled?,
+            maxSeconds: config.max_video_seconds.to_i,
+            maxSize: config.max_video_size.to_i
+          },
+          avatars: {
+            enabled: config.avatars_enabled?,
+            maxSize: config.max_avatar_size.to_i
+          },
+          nps: { enabled: config.nps ? true : false },
+          labels: labels
+        }
+        # Escape "</" so a value can't close the <script> block early.
+        payload.to_json.gsub('</', '<\/')
+      end
+
+      private
+
+      def existing_video_url(existing)
+        return unless existing.video_attached?
+
+        "#{Testimonials.config.mount_path.chomp('/')}/#{existing.id}/video"
+      end
+
+      # Every user-facing string in the widget, resolved through Rails I18n so
+      # the form follows the app's current locale. Each lookup carries an
+      # English default, so the widget stays fully worded even when a key is
+      # missing for the active locale.
+      def labels
+        app = Testimonials.app_name
+        {
+          enjoying: t(:enjoying, 'Enjoying %{app}?', app: app),
+          notNow: t(:not_now, 'Not now'),
+          rateAria: t(:rate_aria, 'Rate %{count} of 5'),
+          shareTitle: t(:share_title, 'Share your experience'),
+          updateTitle: t(:update_title, 'Update your review'),
+          promoterTitle: t(:promoter_title, 'Glad to hear it! Mind saying that publicly?'),
+          questionsTitle: t(:questions_title, 'Questions'),
+          message: t(:message, 'Your testimonial'),
+          messagePlaceholder: t(:message_placeholder, 'What would you tell a friend about %{app}?', app: app),
+          recordVideo: t(:record_video, 'Record a video'),
+          recordVideoHint: t(:record_video_hint, 'A short video says more than a page of text.'),
+          name: t(:name, 'Your name'),
+          email: t(:email, 'Your email'),
+          titleCompany: t(:title_company, 'Title, company'),
+          photo: t(:photo, 'Your photo'),
+          optional: t(:optional, 'optional'),
+          submit: t(:submit, 'Send'),
+          cancel: t(:cancel, 'Cancel'),
+          close: t(:close, 'Close'),
+          thanks: t(:thanks, 'Thank you so much!'),
+          videoCheckTitle: t(:video_check_title, 'Camera check'),
+          videoHint: t(:video_hint, 'Up to %{seconds} seconds. You can review it before sending.',
+                       seconds: Testimonials.config.max_video_seconds.to_i),
+          startRecording: t(:start_recording, 'Start recording'),
+          stopRecording: t(:stop_recording, 'Finish'),
+          recordAgain: t(:record_again, 'Record again'),
+          useVideo: t(:use_video, 'Use this video'),
+          uploadInstead: t(:upload_instead, 'Upload a video file instead'),
+          videoAttached: t(:video_attached, 'Video attached'),
+          remove: t(:remove, 'Remove'),
+          npsQuestion: t(:nps_question, 'How likely are you to recommend %{app} to a friend or colleague?', app: app),
+          npsLow: t(:nps_low, 'Not at all likely'),
+          npsHigh: t(:nps_high, 'Extremely likely'),
+          npsCommentLabel: t(:nps_comment_label, "What's the main reason for your score?"),
+          errorBlank: t(:error_blank, 'Please write something or record a video.'),
+          errorContact: t(:error_contact, 'Please enter your name and email.'),
+          errorSave: t(:error_save, 'Could not send. Please try again.'),
+          errorVideoTooLarge: t(:error_video_too_large, 'The video is too large (max %{size} MB).',
+                                size: Testimonials.config.max_video_size.to_i / (1024 * 1024)),
+          errorCamera: t(:error_camera, 'Could not access the camera. You can upload a video file instead.')
+        }
+      end
+
+      def t(key, default, **args)
+        I18n.t(key, scope: :testimonials, default: default, **args)
+      end
+
+      def rtl?(locale)
+        RTL_LANGUAGES.include?(locale.to_s.downcase.split(/[-_]/).first)
+      end
+    end
+  end
+end

data/lib/testimonials.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'testimonials/version'
+require 'testimonials/configuration'
+require 'testimonials/widget'
+require 'testimonials/prompt_helper'
+require 'testimonials/engine'
+
+# Testimonials, reviews and NPS for Rails. An iOS-style in-app widget collects
+# star ratings and testimonials (text or video) at moments your code chooses;
+# a public page collects them from shareable links; NPS promoters are routed
+# straight into the testimonial ask. Everything lands in your own database
+# with a minimal dashboard to approve, feature, and pick best lines — and a read API
+# to render approved testimonials wherever you like.
+module Testimonials
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Can this request see the widget and submit? Checked on the server for
+    # every public endpoint and by the helper before rendering.
+    def enabled?(request)
+      !!config.enabled.call(request)
+    end
+
+    # Can this request browse and triage submissions? Checked by every
+    # dashboard action.
+    def admin?(request)
+      !!config.authorize_admin.call(request)
+    end
+
+    def app_name
+      config.app_name.presence || rails_app_name
+    end
+
+    # The guiding questions for the current locale, with %{app} filled in.
+    # I18n leaves the token alone when no interpolation values are passed,
+    # so a plain gsub covers built-in, literal, and lambda-provided strings
+    # alike.
+    def questions
+      list = config.questions
+      list = list.call if list.respond_to?(:call)
+      list = I18n.t('testimonials.questions', default: []) if list.nil?
+      Array(list).map { |q| q.to_s.gsub('%{app}', app_name) }
+    end
+
+    def consent_text
+      config.consent_text.presence ||
+        I18n.t('testimonials.consent',
+               default: 'I give permission to use this testimonial across social channels ' \
+                        'and other marketing efforts.')
+    end
+
+    private
+
+    # The application's module name, verbatim ("EthicsPortal", "SupeRails") —
+    # no inflection games. Set config.app_name for anything fancier.
+    def rails_app_name
+      Rails.application.class.module_parent_name
+    rescue StandardError
+      'this app'
+    end
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: testimonials
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yaroslav Shmarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: |
+  A mountable Rails engine that collects customer testimonials — text and
+  video — and NPS scores from inside your app. An iOS-style "Enjoying this
+  app?" widget prompts users at moments your code chooses (with built-in
+  throttling), a public page collects testimonials from a shareable link,
+  and a minimal dashboard lets you approve, feature, and excerpt what comes
+  in. Display is headless: approved testimonials are served through your
+  models or an optional JSON API, and you render them with your own markup.
+  Framework-agnostic: no CSS or JS framework required.
+email:
+- yaroslav.shmarov@clickfunnels.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/testimonials/api/base_controller.rb
+- app/controllers/testimonials/api/stats_controller.rb
+- app/controllers/testimonials/api/testimonials_controller.rb
+- app/controllers/testimonials/application_controller.rb
+- app/controllers/testimonials/collection_controller.rb
+- app/controllers/testimonials/events_controller.rb
+- app/controllers/testimonials/media_controller.rb
+- app/controllers/testimonials/nps_controller.rb
+- app/controllers/testimonials/nps_responses_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
+- app/models/testimonials/testimonial.rb
+- app/views/layouts/testimonials/application.html.erb
+- app/views/layouts/testimonials/collection.html.erb
+- app/views/testimonials/collection/show.html.erb
+- app/views/testimonials/nps_responses/index.html.erb
+- app/views/testimonials/testimonials/index.html.erb
+- app/views/testimonials/testimonials/show.html.erb
+- config/locales/testimonials.ar.yml
+- config/locales/testimonials.bg.yml
+- config/locales/testimonials.bn.yml
+- config/locales/testimonials.de.yml
+- config/locales/testimonials.el.yml
+- config/locales/testimonials.en.yml
+- config/locales/testimonials.es.yml
+- config/locales/testimonials.fr.yml
+- config/locales/testimonials.hi.yml
+- config/locales/testimonials.hr.yml
+- config/locales/testimonials.id.yml
+- config/locales/testimonials.it.yml
+- config/locales/testimonials.ja.yml
+- config/locales/testimonials.ko.yml
+- config/locales/testimonials.lb.yml
+- config/locales/testimonials.nl.yml
+- config/locales/testimonials.pl.yml
+- config/locales/testimonials.pt.yml
+- config/locales/testimonials.ro.yml
+- config/locales/testimonials.ru.yml
+- config/locales/testimonials.th.yml
+- config/locales/testimonials.tr.yml
+- config/locales/testimonials.uk.yml
+- config/locales/testimonials.ur.yml
+- config/locales/testimonials.vi.yml
+- config/locales/testimonials.zh-CN.yml
+- config/routes.rb
+- 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/testimonials.rb
+- lib/testimonials/configuration.rb
+- lib/testimonials/dashboard.js
+- lib/testimonials/engine.rb
+- lib/testimonials/prompt_helper.rb
+- lib/testimonials/version.rb
+- lib/testimonials/widget.js
+- lib/testimonials/widget.rb
+homepage: https://github.com/yshmarov/testimonials-engine
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yshmarov/testimonials-engine
+  source_code_uri: https://github.com/yshmarov/testimonials-engine
+  changelog_uri: https://github.com/yshmarov/testimonials-engine/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/yshmarov/testimonials-engine/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: 'Testimonials, reviews and NPS for Rails: in-app collection widget, public
+  collection page, triage dashboard, and a read API.'
+test_files: []