ticket 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a3f38c0710642e9e5f71760700c87eb76fab7185e6232791221e06b400871701
+  data.tar.gz: 560960719fff0060ba693ade1bf7f7ea860f8a21247ab1ce22e7d00fa5d38eee
+SHA512:
+  metadata.gz: 73ad1d85a11a898bed9f6bf0d8c226bd67d904e3808aeb2ee954e9be983e796067a70f69485e7b7f58cb6b531e1ec69399a88d40ea9c9f23263a20fcb46b687b
+  data.tar.gz: c04307fd9663e4aaf0808c1925f8e8b9fd811682c8d8b288a71eee032136b362e3aeb131e4347a5b44d474cc2e5d20de5e1a405ee418a8aa4fa698b96a3d5053

data/MIT-LICENSE

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

data/README.md

@@ -0,0 +1,76 @@
+# Ticket
+
+A feedback button for our Rails apps. The people using an app report a bug, an idea or a question, with a screenshot if they want, without a GitHub account. Each report becomes an issue in that app's repository.
+
+- A small **Feedback** button in the corner of every page, for signed-in people only.
+- They pick a kind, write what happened, and can capture the current tab, paste, drop or choose an image.
+- The page, the browser, the app version, the Rails request id and the last JavaScript errors are sent with it.
+- The report is saved in the app's database first, then a job files the issue. Nothing is lost if GitHub is down; a refused token marks the report `failed` with the reason.
+- The issue links to the screenshot, which is served by the app behind its own sign-in.
+
+The widget is a plain JavaScript custom element in a shadow root, served by the app's asset pipeline. It does not touch the app's JavaScript bundle, Stimulus, Tailwind or CSS. Its text is in French and English, following `I18n.locale`.
+
+## Install in an app
+
+```ruby
+# Gemfile
+gem "ticket", github: "boxprod/ticket"
+```
+
+```sh
+bundle install
+bin/rails ticket:install:migrations db:migrate
+```
+
+```ruby
+# config/routes.rb
+mount Ticket::Engine => "/ticket"
+```
+
+```ruby
+# config/initializers/ticket.rb
+Ticket.configure do |config|
+  config.repository = "boxprod/the-app"
+  config.github_token = Rails.application.credentials.dig(:ticket, :github_token)
+  config.current_reporter = -> { Current.user }   # nil hides the button and refuses reports
+end
+```
+
+```erb
+<%# app/views/layouts/application.html.erb, at the end of <body> %>
+<%= ticket_widget %>
+```
+
+Without a token, reports are kept in `ticket_reports` but not sent: that is what happens in development.
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `repository` | — | `"owner/name"` |
+| `github_token` | — | Fine-grained token with **Issues: read and write** on the repository |
+| `current_reporter` | `-> { nil }` | Run in the controller and the view |
+| `reporter_name` | `name`, then `email_address` | Gets the reporter, returns the name shown in the issue |
+| `labels` | `["feedback"]` | The kind (`bug`, `idea`, `question`) is added |
+| `parent_controller` | `"::ApplicationController"` | Its authentication applies to the engine |
+| `app_version` | `KAMAL_VERSION` or `GIT_REVISION` | String or lambda |
+| `max_screenshot_size` | 8 MB | |
+
+### The GitHub token
+
+Create a fine-grained personal access token (GitHub → Settings → Developer settings) with **boxprod** as its resource owner (the organization must allow fine-grained tokens: Settings → Personal access tokens), limited to the app's repository, with **Issues: read and write** and nothing else. Issues are opened in the name of the token's owner; the reporter's name is in the body. If GitHub refuses the labels, the issue is filed without them.
+
+### Reports that were not sent
+
+```sh
+bin/rails ticket:redeliver
+```
+
+## Development
+
+```sh
+bundle install
+bin/rails db:migrate
+bin/rails test
+CHROMIUM=/usr/bin/chromium bin/rails test:system   # the widget in headless Chromium, tab capture included
+```

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/javascripts/ticket/widget.js

@@ -0,0 +1,301 @@
+// The feedback button: a custom element in a shadow root, so neither the host's CSS nor its
+// JavaScript bundle is involved. Served as is by the host's asset pipeline.
+
+const MAX_WIDTH = 2560
+const MAX_ERRORS = 10
+
+// Kept at module level: Turbo replaces the element on every visit, the draft survives it.
+const draft = { open: false, kind: "bug", description: "", screenshot: null }
+const errors = []
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function remember(message) {
+  errors.push(`${new Date().toISOString()} ${message}`.slice(0, 500))
+  if (errors.length > MAX_ERRORS) errors.shift()
+}
+
+window.addEventListener("error", (event) => remember(`${event.message} (${event.filename}:${event.lineno})`))
+window.addEventListener("unhandledrejection", (event) => remember(`Unhandled rejection: ${event.reason}`))
+
+const STYLE = `
+  :host { all: initial; font: 13px/1.4 system-ui, -apple-system, "Segoe UI", sans-serif; color: #18181b;
+          --border: #d4d4d8; --muted: #71717a; --surface: #fff; --soft: #f4f4f5; --text: #18181b; }
+  :host([hidden]) { display: none !important; }
+  * { box-sizing: border-box; font: inherit; }
+  [hidden] { display: none !important; }
+  .toggle { position: fixed; right: 16px; bottom: 16px; z-index: 2147483000; padding: 6px 12px;
+            border: 1px solid var(--border); border-radius: 6px; background: var(--surface); color: var(--text);
+            box-shadow: 0 1px 2px rgb(0 0 0 / .08); cursor: pointer; }
+  .toggle:hover { background: var(--soft); }
+  .panel { position: fixed; right: 16px; bottom: 56px; z-index: 2147483001; width: min(380px, calc(100vw - 32px));
+           max-height: calc(100vh - 72px); overflow: auto; padding: 14px; border: 1px solid var(--border);
+           border-radius: 8px; background: var(--surface); color: var(--text); box-shadow: 0 8px 24px rgb(0 0 0 / .12); }
+  header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px; }
+  h2 { margin: 0; font-weight: 600; font-size: 14px; }
+  button { cursor: pointer; }
+  .close { border: 0; background: none; color: var(--muted); font-size: 18px; line-height: 1; padding: 2px 4px; }
+  fieldset { border: 0; padding: 0; margin: 0 0 10px; display: flex; flex-direction: column; gap: 4px; }
+  label.kind { display: flex; align-items: center; gap: 6px; }
+  label.kind input { margin: 0; }
+  textarea { width: 100%; min-height: 110px; resize: vertical; padding: 8px; border: 1px solid var(--border);
+             border-radius: 6px; background: var(--surface); color: var(--text); }
+  textarea:focus { outline: 2px solid #3f3f46; outline-offset: -1px; }
+  .hint { margin: 4px 0 10px; color: var(--muted); font-size: 12px; }
+  .shot { border: 1px dashed var(--border); border-radius: 6px; padding: 8px; margin-bottom: 12px; }
+  .shot.over { background: var(--soft); }
+  .shot-actions { display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+  .shot img { display: block; max-width: 100%; max-height: 180px; margin: 0 auto 6px; border: 1px solid var(--border); }
+  .secondary { padding: 4px 8px; border: 1px solid var(--border); border-radius: 6px; background: var(--surface); color: var(--text); }
+  .secondary:hover { background: var(--soft); }
+  .footer { display: flex; align-items: center; justify-content: space-between; gap: 8px; }
+  .message { color: var(--muted); font-size: 12px; }
+  .message.error { color: #b91c1c; }
+  .submit { padding: 6px 14px; border: 1px solid #18181b; border-radius: 6px; background: #18181b; color: #fff; }
+  .submit:disabled { opacity: .5; cursor: default; }
+  .done p { margin: 0 0 12px; }
+`
+
+class TicketWidget extends HTMLElement {
+  connectedCallback() {
+    if (this.shadowRoot) return
+
+    this.strings = JSON.parse(this.dataset.strings || "{}")
+    this.attachShadow({ mode: "open" })
+    this.render()
+    this.restore()
+  }
+
+  t(key) {
+    return key.split(".").reduce((value, part) => value?.[part], this.strings) ?? key
+  }
+
+  render() {
+    const kinds = ["bug", "idea", "question"].map((kind) => `
+      <label class="kind"><input type="radio" name="kind" value="${kind}"> ${this.escape(this.t(`kinds.${kind}`))}</label>`).join("")
+
+    this.shadowRoot.innerHTML = `
+      <style>${STYLE}</style>
+      <button type="button" class="toggle" part="toggle" aria-expanded="false">${this.escape(this.t("button"))}</button>
+      <section class="panel" role="dialog" aria-label="${this.escape(this.t("title"))}" hidden>
+        <header>
+          <h2>${this.escape(this.t("title"))}</h2>
+          <button type="button" class="close" aria-label="${this.escape(this.t("close"))}">×</button>
+        </header>
+        <form class="form" novalidate>
+          <fieldset>${kinds}</fieldset>
+          <textarea name="description" required placeholder="${this.escape(this.t("description"))}"></textarea>
+          <p class="hint">${this.escape(this.t("description_hint"))}</p>
+          <div class="shot">
+            <img alt="" hidden>
+            <div class="shot-actions">
+              <button type="button" class="secondary capture">${this.escape(this.t("capture"))}</button>
+              <button type="button" class="secondary choose">${this.escape(this.t("choose"))}</button>
+              <button type="button" class="secondary remove" hidden>${this.escape(this.t("remove"))}</button>
+              <span class="message paste-hint">${this.escape(this.t("paste_hint"))}</span>
+            </div>
+            <input type="file" accept="image/png,image/jpeg,image/webp" hidden>
+          </div>
+          <div class="footer">
+            <span class="message status" role="status"></span>
+            <button type="submit" class="submit">${this.escape(this.t("submit"))}</button>
+          </div>
+        </form>
+        <div class="done" hidden>
+          <p>${this.escape(this.t("sent"))}</p>
+          <div class="footer">
+            <button type="button" class="secondary another">${this.escape(this.t("another"))}</button>
+            <button type="button" class="secondary close-done">${this.escape(this.t("close"))}</button>
+          </div>
+        </div>
+      </section>`
+
+    const $ = (selector) => this.shadowRoot.querySelector(selector)
+    this.els = {
+      toggle: $(".toggle"), panel: $(".panel"), form: $(".form"), done: $(".done"),
+      description: $("textarea"), image: $(".shot img"), shot: $(".shot"), file: $("input[type=file]"),
+      capture: $(".capture"), remove: $(".remove"), status: $(".status"), submit: $(".submit")
+    }
+
+    if (!navigator.mediaDevices?.getDisplayMedia) this.els.capture.hidden = true
+
+    this.els.toggle.addEventListener("click", () => this.setOpen(!draft.open))
+    $(".close").addEventListener("click", () => this.setOpen(false))
+    $(".close-done").addEventListener("click", () => { this.reset(); this.setOpen(false) })
+    $(".another").addEventListener("click", () => this.reset())
+    $(".choose").addEventListener("click", () => this.els.file.click())
+    this.els.capture.addEventListener("click", () => this.capture())
+    this.els.remove.addEventListener("click", () => this.setScreenshot(null))
+    this.els.file.addEventListener("change", () => this.takeFile(this.els.file.files[0]))
+    this.els.description.addEventListener("input", () => { draft.description = this.els.description.value })
+    this.shadowRoot.querySelectorAll("input[name=kind]").forEach((input) =>
+      input.addEventListener("change", () => { draft.kind = input.value }))
+    this.els.form.addEventListener("submit", (event) => { event.preventDefault(); this.submit() })
+
+    this.els.shot.addEventListener("dragover", (event) => { event.preventDefault(); this.els.shot.classList.add("over") })
+    this.els.shot.addEventListener("dragleave", () => this.els.shot.classList.remove("over"))
+    this.els.shot.addEventListener("drop", (event) => {
+      event.preventDefault()
+      this.els.shot.classList.remove("over")
+      this.takeFile(event.dataTransfer.files[0])
+    })
+
+    // What is typed or pasted in the panel stays in it. Seen from the page, the focus is on
+    // <ticket-widget>, not on a field, so the page's own shortcuts would take these keys.
+    for (const type of ["keydown", "keyup", "keypress", "paste", "copy", "cut"]) {
+      this.els.panel.addEventListener(type, (event) => event.stopPropagation())
+    }
+    this.els.panel.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") { this.setOpen(false); this.els.toggle.focus() }
+      if (event.key === "Enter" && (event.metaKey || event.ctrlKey) && !this.els.form.hidden) this.submit()
+    })
+    this.els.panel.addEventListener("paste", (event) => {
+      const file = [...(event.clipboardData?.files || [])].find((item) => item.type.startsWith("image/"))
+      if (file) { event.preventDefault(); this.takeFile(file) }
+    })
+  }
+
+  restore() {
+    this.els.description.value = draft.description
+    this.shadowRoot.querySelector(`input[value=${draft.kind}]`).checked = true
+    this.setScreenshot(draft.screenshot)
+    this.setOpen(draft.open, { focus: false })
+  }
+
+  setOpen(open, { focus = true } = {}) {
+    draft.open = open
+    this.els.panel.hidden = !open
+    this.els.toggle.setAttribute("aria-expanded", String(open))
+    if (open && focus) this.els.description.focus()
+  }
+
+  setScreenshot(blob) {
+    if (this.previewUrl) URL.revokeObjectURL(this.previewUrl)
+    this.previewUrl = null
+    draft.screenshot = blob
+
+    if (blob) {
+      this.previewUrl = URL.createObjectURL(blob)
+      this.els.image.src = this.previewUrl
+    } else {
+      this.els.image.removeAttribute("src")
+      this.els.file.value = ""
+    }
+    this.els.image.hidden = !blob
+    this.els.remove.hidden = !blob
+  }
+
+  async takeFile(file) {
+    if (!file || !file.type.startsWith("image/")) return
+    try {
+      const bitmap = await createImageBitmap(file)
+      this.setScreenshot(await this.encode(bitmap, bitmap.width, bitmap.height))
+      bitmap.close()
+      this.showStatus("")
+    } catch {
+      this.showStatus(this.t("capture_failed"), true)
+    }
+  }
+
+  // The current tab, picked in the browser's own dialog. The widget steps aside once sharing starts:
+  // a still page sends frames only when it repaints, and hiding the widget is that repaint.
+  async capture() {
+    let stream
+    try {
+      stream = await navigator.mediaDevices.getDisplayMedia({
+        video: { displaySurface: "browser" }, audio: false, preferCurrentTab: true, selfBrowserSurface: "include"
+      })
+      this.hidden = true
+      const video = document.createElement("video")
+      video.muted = true
+      video.srcObject = stream
+      await Promise.race([video.play(), wait(3000).then(() => { throw new Error("no frame") })])
+      // Let the browser's sharing bar leave the picture.
+      await wait(400)
+      await new Promise((resolve) => { video.requestVideoFrameCallback?.(resolve); setTimeout(resolve, 300) })
+      if (!video.videoWidth) throw new Error("no frame")
+      this.setScreenshot(await this.encode(video, video.videoWidth, video.videoHeight))
+      this.showStatus("")
+    } catch (error) {
+      if (error?.name !== "NotAllowedError") this.showStatus(this.t("capture_failed"), true)
+    } finally {
+      stream?.getTracks().forEach((track) => track.stop())
+      this.hidden = false
+    }
+  }
+
+  async encode(source, width, height) {
+    const scale = Math.min(1, MAX_WIDTH / width)
+    const canvas = document.createElement("canvas")
+    canvas.width = Math.round(width * scale)
+    canvas.height = Math.round(height * scale)
+    canvas.getContext("2d").drawImage(source, 0, 0, canvas.width, canvas.height)
+    return new Promise((resolve, reject) =>
+      canvas.toBlob((blob) => (blob ? resolve(blob) : reject(new Error("encode"))), "image/webp", 0.9))
+  }
+
+  async submit() {
+    if (!this.els.description.value.trim()) {
+      this.els.description.focus()
+      return
+    }
+
+    const body = new FormData()
+    body.append("kind", draft.kind)
+    body.append("description", this.els.description.value)
+    body.append("page_url", location.href)
+    body.append("page_title", document.title)
+    if (this.dataset.requestId) body.append("page_request_id", this.dataset.requestId)
+    body.append("browser[viewport]", `${innerWidth}×${innerHeight}`)
+    body.append("browser[screen]", `${screen.width}×${screen.height} @${devicePixelRatio}x`)
+    body.append("browser[language]", navigator.language)
+    body.append("browser[timezone]", Intl.DateTimeFormat().resolvedOptions().timeZone)
+    errors.forEach((error) => body.append("errors[]", error))
+    if (draft.screenshot) body.append("screenshot", draft.screenshot, `screenshot.${draft.screenshot.type.split("/")[1]}`)
+
+    this.els.submit.disabled = true
+    this.showStatus(this.t("sending"))
+    try {
+      const response = await fetch(this.dataset.endpoint, {
+        method: "POST",
+        body,
+        credentials: "same-origin",
+        headers: { "X-CSRF-Token": document.querySelector("meta[name=csrf-token]")?.content || "", Accept: "application/json" }
+      })
+      if (response.ok) {
+        this.els.form.hidden = true
+        this.els.done.hidden = false
+        this.showStatus("")
+      } else if (response.status === 401 || response.status === 422 && !(await response.clone().json().catch(() => null))) {
+        this.showStatus(this.t("signed_out"), true)
+      } else if (response.status === 413) {
+        this.showStatus(this.t("image_too_large"), true)
+      } else {
+        this.showStatus(this.t("failed"), true)
+      }
+    } catch {
+      this.showStatus(this.t("failed"), true)
+    } finally {
+      this.els.submit.disabled = false
+    }
+  }
+
+  reset() {
+    draft.kind = "bug"
+    draft.description = ""
+    this.setScreenshot(null)
+    this.els.form.hidden = false
+    this.els.done.hidden = true
+    this.restore()
+  }
+
+  showStatus(text, error = false) {
+    this.els.status.textContent = text
+    this.els.status.classList.toggle("error", error)
+  }
+
+  escape(text) {
+    return String(text).replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`)
+  }
+}
+
+if (!customElements.get("ticket-widget")) customElements.define("ticket-widget", TicketWidget)

data/app/controllers/ticket/application_controller.rb

@@ -0,0 +1,13 @@
+module Ticket
+  # Inherits from the host's controller so its authentication, locale and browser rules apply.
+  class ApplicationController < Ticket.config.parent_controller.constantize
+    private
+      def current_reporter
+        @current_reporter ||= instance_exec(&Ticket.config.current_reporter)
+      end
+
+      def require_reporter
+        head :unauthorized unless current_reporter
+      end
+  end
+end

data/app/controllers/ticket/reports_controller.rb

@@ -0,0 +1,51 @@
+module Ticket
+  class ReportsController < ApplicationController
+    before_action :require_reporter
+
+    def create
+      report = Report.new(report_params)
+      report.reporter = current_reporter
+      report.screenshot_upload = params[:screenshot]
+      report.context = context
+
+      if report.save
+        report.deliver_later
+        render json: { id: report.id }, status: :created
+      else
+        render json: { errors: report.errors.full_messages }, status: :unprocessable_content
+      end
+    end
+
+    # The screenshot an issue links to; behind the host's sign-in like any other page.
+    def screenshot
+      report = Report.find(params[:id])
+      return head :not_found unless report.screenshot?
+
+      send_data report.screenshot, type: report.screenshot_content_type, disposition: :inline,
+        filename: "ticket-#{report.id}.#{Report::IMAGE_TYPES.fetch(report.screenshot_content_type)}"
+    end
+
+    private
+      def report_params
+        params.permit(:kind, :description, :page_url, :page_title)
+      end
+
+      def context
+        browser = params.fetch(:browser, {}).permit(:viewport, :screen, :language, :timezone).to_h
+        {
+          "user_agent" => request.user_agent,
+          "request_id" => params[:page_request_id].presence,
+          "app_version" => app_version,
+          "environment" => Rails.env,
+          "engine_url" => request.base_url + request.script_name,
+          "browser" => browser,
+          "errors" => Array(params[:errors]).first(10).map { |error| error.to_s.first(500) }
+        }.compact_blank
+      end
+
+      def app_version
+        version = Ticket.config.app_version
+        version.respond_to?(:call) ? version.call : version
+      end
+  end
+end

data/app/helpers/ticket/widget_helper.rb

@@ -0,0 +1,18 @@
+module Ticket
+  # `<%= ticket_widget %>` in the host's layout: the button, for signed-in people only.
+  module WidgetHelper
+    def ticket_widget
+      return unless respond_to?(:ticket) && instance_exec(&Ticket.config.current_reporter)
+
+      safe_join [
+        tag.ticket_widget(data: { endpoint: ticket.reports_path, request_id: request&.request_id, strings: t("ticket.widget").to_json }),
+        javascript_include_tag("ticket/widget", type: "module", nonce: true)
+      ]
+    rescue StandardError => error
+      # The host's page matters more than the feedback button.
+      raise unless Rails.env.production?
+      Rails.logger.error("[ticket] widget not rendered: #{error.class}: #{error.message}")
+      nil
+    end
+  end
+end

data/app/jobs/ticket/deliver_job.rb

@@ -0,0 +1,23 @@
+module Ticket
+  # Not the host's ApplicationJob: none of its callbacks or retries apply here.
+  class DeliverJob < ActiveJob::Base
+    queue_as :default
+
+    retry_on GitHub::Error, wait: :polynomially_longer, attempts: 10 do |job, error|
+      job.arguments.first.update!(state: :failed, error: error.message)
+    end
+
+    discard_on GitHub::Rejected do |job, error|
+      job.arguments.first.update!(state: :failed, error: error.message)
+    end
+
+    discard_on ActiveJob::DeserializationError
+
+    def perform(report)
+      return if report.sent?
+
+      issue = Ticket.client.create_issue(title: report.title, body: IssueBody.new(report).to_s, labels: report.labels)
+      report.update!(state: :sent, issue_number: issue[:number], issue_url: issue[:url], error: nil)
+    end
+  end
+end

data/app/models/ticket/application_record.rb

@@ -0,0 +1,5 @@
+module Ticket
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/ticket/issue_body.rb

@@ -0,0 +1,54 @@
+module Ticket
+  # The Markdown of the issue: the report in the reporter's words, then what was collected around it.
+  class IssueBody
+    def initialize(report)
+      @report = report
+      @context = report.context || {}
+    end
+
+    def to_s
+      [ description, screenshot, reporter, details ].compact.join("\n\n")
+    end
+
+    private
+      def description
+        @report.description.strip
+      end
+
+      def screenshot
+        "**Screenshot:** [view](#{@report.screenshot_url}) (sign in to the app to open it)" if @report.screenshot_url
+      end
+
+      def reporter
+        page = @report.page_url.present? ? "[#{escape(@report.page_title.presence || @report.page_url)}](<#{@report.page_url.delete("<>")}>)" : "unknown page"
+        "Reported by **#{escape(@report.reporter_name)}** on #{page}, #{@report.created_at.utc.strftime("%Y-%m-%d %H:%M UTC")}."
+      end
+
+      def details
+        rows = {
+          "Report" => "##{@report.id}",
+          "Version" => @context["app_version"],
+          "Environment" => @context["environment"],
+          "Request" => @context["request_id"],
+          "Browser" => @context["user_agent"],
+          "Viewport" => @context.dig("browser", "viewport"),
+          "Screen" => @context.dig("browser", "screen"),
+          "Language" => @context.dig("browser", "language"),
+          "Time zone" => @context.dig("browser", "timezone")
+        }.compact_blank
+
+        table = rows.map { |name, value| "| #{name} | `#{value.to_s.delete("`|")}` |" }
+        lines = [ "<details><summary>Context</summary>", "", "| | |", "|---|---|", *table ]
+
+        if (errors = @context["errors"]).present?
+          lines += [ "", "JavaScript errors on the page:", "", "```", *errors, "```" ]
+        end
+
+        (lines + [ "", "</details>" ]).join("\n")
+      end
+
+      def escape(text)
+        text.to_s.gsub(/[\[\]<>*_`]/) { |char| "\\#{char}" }
+      end
+  end
+end

data/app/models/ticket/report.rb

@@ -0,0 +1,58 @@
+module Ticket
+  # A report kept in the host's database, so nothing is lost while GitHub is unreachable.
+  class Report < ApplicationRecord
+    KINDS = %w[ bug idea question ].freeze
+    IMAGE_TYPES = { "image/png" => "png", "image/jpeg" => "jpg", "image/webp" => "webp" }.freeze
+
+    enum :state, { pending: "pending", sent: "sent", failed: "failed" }, default: "pending"
+
+    serialize :context, coder: JSON
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :description, presence: true, length: { maximum: 20_000 }
+    validates :screenshot_content_type, inclusion: { in: IMAGE_TYPES.keys }, allow_nil: true
+    validate :screenshot_within_limit
+
+    # What `ticket:redeliver` sends again.
+    scope :undelivered, -> { where.not(state: "sent") }
+
+    def reporter=(reporter)
+      self.reporter_id = reporter.try(:id)&.to_s
+      self.reporter_name = Ticket.config.reporter_name.call(reporter).to_s.first(200)
+      self.reporter_email = reporter.try(:email_address) || reporter.try(:email)
+    end
+
+    def screenshot_upload=(upload)
+      return unless upload.respond_to?(:read)
+
+      self.screenshot_content_type = upload.content_type
+      self.screenshot = upload.read
+    end
+
+    def screenshot?
+      screenshot.present?
+    end
+
+    def deliver_later
+      DeliverJob.perform_later(self) if Ticket.config.deliver?
+    end
+
+    def title
+      "[#{kind.capitalize}] #{description.squish.truncate(80)}"
+    end
+
+    # The engine's address as the reporter saw it, so the issue can link back to the screenshot.
+    def screenshot_url
+      "#{context["engine_url"]}/reports/#{id}/screenshot" if screenshot? && context&.dig("engine_url")
+    end
+
+    def labels
+      Ticket.config.labels + [ kind ]
+    end
+
+    private
+      def screenshot_within_limit
+        errors.add(:screenshot, :too_long, count: Ticket.config.max_screenshot_size) if screenshot.to_s.bytesize > Ticket.config.max_screenshot_size
+      end
+  end
+end

data/config/locales/ticket.en.yml

@@ -0,0 +1,24 @@
+en:
+  ticket:
+    widget:
+      button: Feedback
+      title: Send feedback
+      kinds:
+        bug: Something is wrong
+        idea: An idea
+        question: A question
+      description: What happened, or what would help?
+      description_hint: The page you are on and your browser are sent with it.
+      capture: Capture the screen
+      choose: Choose an image
+      paste_hint: or paste or drop an image here
+      remove: Remove
+      capture_failed: The screen could not be captured.
+      image_too_large: This image is too large.
+      submit: Send
+      sending: Sending…
+      sent: Thank you, it has been sent to the team.
+      signed_out: Your session has ended. Sign in again, then send it.
+      failed: It could not be sent. Try again in a moment.
+      close: Close
+      another: Send another

data/config/locales/ticket.fr.yml

@@ -0,0 +1,24 @@
+fr:
+  ticket:
+    widget:
+      button: Signaler
+      title: Faire un retour
+      kinds:
+        bug: Quelque chose ne va pas
+        idea: Une idée
+        question: Une question
+      description: Que s’est-il passé, ou qu’est-ce qui aiderait ?
+      description_hint: La page où vous êtes et votre navigateur sont envoyés avec.
+      capture: Capturer l’écran
+      choose: Choisir une image
+      paste_hint: ou collez ou déposez une image ici
+      remove: Retirer
+      capture_failed: L’écran n’a pas pu être capturé.
+      image_too_large: Cette image est trop lourde.
+      submit: Envoyer
+      sending: Envoi…
+      sent: Merci, c’est transmis à l’équipe.
+      signed_out: Votre session a expiré. Reconnectez-vous, puis envoyez.
+      failed: L’envoi a échoué. Réessayez dans un instant.
+      close: Fermer
+      another: En envoyer un autre

data/config/routes.rb

@@ -0,0 +1,5 @@
+Ticket::Engine.routes.draw do
+  resources :reports, only: :create do
+    get :screenshot, on: :member
+  end
+end

data/db/migrate/20261006000000_create_ticket_reports.rb

@@ -0,0 +1,23 @@
+class CreateTicketReports < ActiveRecord::Migration[8.0]
+  def change
+    create_table :ticket_reports do |t|
+      t.string :kind, null: false
+      t.text :description, null: false
+      t.string :page_url
+      t.string :page_title
+      t.string :reporter_id
+      t.string :reporter_name
+      t.string :reporter_email
+      t.text :context
+      t.binary :screenshot
+      t.string :screenshot_content_type
+      t.string :state, null: false, default: "pending"
+      t.integer :issue_number
+      t.string :issue_url
+      t.text :error
+      t.timestamps
+    end
+
+    add_index :ticket_reports, :state
+  end
+end

data/lib/tasks/ticket_tasks.rake

@@ -0,0 +1,12 @@
+namespace :ticket do
+  desc "Send again the reports GitHub has not received"
+  task redeliver: :environment do
+    abort "Ticket has no repository or token to deliver to" unless Ticket.config.deliver?
+
+    Ticket::Report.undelivered.find_each do |report|
+      report.update!(state: :pending, error: nil)
+      Ticket::DeliverJob.perform_later(report)
+      puts "Report ##{report.id} queued"
+    end
+  end
+end

data/lib/ticket/configuration.rb

@@ -0,0 +1,40 @@
+module Ticket
+  class Configuration
+    # "owner/name" of the repository the issues go to.
+    attr_accessor :repository
+
+    # A token allowed to create issues in that repository. Without one, reports are kept but not sent.
+    attr_accessor :github_token
+
+    # Labels added to every issue, before the one for the kind of report.
+    attr_accessor :labels
+
+    # Called in the controller and the view; returns the person reporting, or nil to hide the widget.
+    attr_accessor :current_reporter
+
+    # How a reporter is named in the issue. Gets the object current_reporter returned.
+    attr_accessor :reporter_name
+
+    # The host controller the engine's controller inherits from, for its authentication.
+    attr_accessor :parent_controller
+
+    # The deployed version, shown in the issue. A string or a lambda.
+    attr_accessor :app_version
+
+    # The largest screenshot accepted, in bytes.
+    attr_accessor :max_screenshot_size
+
+    def initialize
+      @labels = [ "feedback" ]
+      @current_reporter = -> { nil }
+      @reporter_name = ->(reporter) { reporter.try(:name).presence || reporter.try(:email_address) || reporter.to_s }
+      @parent_controller = "::ApplicationController"
+      @app_version = -> { ENV["KAMAL_VERSION"] || ENV["GIT_REVISION"] }
+      @max_screenshot_size = 8.megabytes
+    end
+
+    def deliver?
+      repository.present? && github_token.present?
+    end
+  end
+end

data/lib/ticket/engine.rb

@@ -0,0 +1,10 @@
+module Ticket
+  class Engine < ::Rails::Engine
+    isolate_namespace Ticket
+
+    # The widget helper is available in every host view, without touching the host's helpers.
+    initializer "ticket.helpers" do
+      ActiveSupport.on_load(:action_view) { include Ticket::WidgetHelper }
+    end
+  end
+end

data/lib/ticket/github.rb

@@ -0,0 +1,61 @@
+require "net/http"
+require "json"
+
+module Ticket
+  # The one call made to GitHub: create an issue. Net::HTTP, so the host takes no new dependency.
+  class GitHub
+    class Error < StandardError; end
+
+    # A refusal that will not change on retry (bad token, missing repository, invalid input).
+    class Rejected < Error; end
+
+    API = URI("https://api.github.com")
+
+    # GitHub out of reach: worth trying again, like an answer in the 500s.
+    NETWORK_ERRORS = [ Net::OpenTimeout, Net::ReadTimeout, SocketError, SystemCallError, OpenSSL::SSL::SSLError, EOFError, IOError ].freeze
+
+    def initialize(token:, repository:)
+      @token = token
+      @repository = repository
+    end
+
+    # Returns { number:, url: }.
+    def create_issue(title:, body:, labels: [])
+      response = post("/repos/#{@repository}/issues", title: title, body: body, labels: labels)
+
+      # Labels are dropped rather than lose the report when the token may not set them.
+      if response.code == "422" && labels.any? && response.body.to_s.include?("label")
+        response = post("/repos/#{@repository}/issues", title: title, body: body)
+      end
+
+      case response
+      when Net::HTTPSuccess
+        issue = JSON.parse(response.body)
+        { number: issue["number"], url: issue["html_url"] }
+      when Net::HTTPTooManyRequests, Net::HTTPServerError
+        raise Error, "GitHub answered #{response.code}: #{response.body.to_s.first(300)}"
+      else
+        raise Rejected, "GitHub answered #{response.code}: #{response.body.to_s.first(300)}"
+      end
+    end
+
+    private
+      def post(path, payload)
+        request = Net::HTTP::Post.new(path)
+        request["Authorization"] = "Bearer #{@token}"
+        request["Accept"] = "application/vnd.github+json"
+        request["X-GitHub-Api-Version"] = "2022-11-28"
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(payload)
+        perform(request)
+      end
+
+      def perform(request)
+        Net::HTTP.start(API.host, API.port, use_ssl: true, open_timeout: 10, read_timeout: 20) do |http|
+          http.request(request)
+        end
+      rescue *NETWORK_ERRORS => error
+        raise Error, "GitHub could not be reached: #{error.class}: #{error.message}"
+      end
+  end
+end

data/lib/ticket/version.rb

@@ -0,0 +1,3 @@
+module Ticket
+  VERSION = "0.1.0"
+end

data/lib/ticket.rb

@@ -0,0 +1,24 @@
+require "ticket/version"
+require "ticket/configuration"
+require "ticket/github"
+require "ticket/engine"
+
+# Feedback from the people using an app, filed as GitHub issues in that app's repository.
+module Ticket
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    # Replaced in tests; anything that answers #create_issue(title:, body:, labels:).
+    attr_writer :client
+
+    def client
+      @client ||= GitHub.new(token: config.github_token, repository: config.repository)
+    end
+  end
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: ticket
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- B.O.X
+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: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Lets the people using an app report a bug, an idea or a question, with
+  a screenshot, without a GitHub account. Each report becomes an issue in the app's
+  repository.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/ticket/widget.js
+- app/controllers/ticket/application_controller.rb
+- app/controllers/ticket/reports_controller.rb
+- app/helpers/ticket/widget_helper.rb
+- app/jobs/ticket/deliver_job.rb
+- app/models/ticket/application_record.rb
+- app/models/ticket/issue_body.rb
+- app/models/ticket/report.rb
+- config/locales/ticket.en.yml
+- config/locales/ticket.fr.yml
+- config/routes.rb
+- db/migrate/20261006000000_create_ticket_reports.rb
+- lib/tasks/ticket_tasks.rake
+- lib/ticket.rb
+- lib/ticket/configuration.rb
+- lib/ticket/engine.rb
+- lib/ticket/github.rb
+- lib/ticket/version.rb
+homepage: https://github.com/boxprod/ticket
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/boxprod/ticket
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: A feedback button for Rails apps that files GitHub issues.
+test_files: []