ideasbugs 0.7.7 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e054b5c1fcb3a26c77783e54d044550ca8a395bad3189540451b79498e36fe0b
-  data.tar.gz: 567787250431c93054d02c0cca2a0366515138c35f9d2ac7a9ed87162d318d9f
+  metadata.gz: 19b7014d62b42ad3b3a763edf8907a7e1e0d2a67ab7b5ae1001d1f3440cc0d67
+  data.tar.gz: 0f327125389c6ccc2d57f180b09d24607f383d03ac1d70ad13c9c250d3670842
 SHA512:
-  metadata.gz: f8542b1c572317d929ae744c2caaeb2e0e59240ad68e740c290d3a15ab4761b9a55cf54b4332b6334667585f45603f9ce9444a3362ccc0a7762ab9c856ee330e
-  data.tar.gz: 8da898919668edb4d3f7d87e76e4223a295bea3374c8e7a355b446277ed08b8983606aecb81544ccf765e1640d26c34f01febaf447bc1950b0e1aa89a771e7fc
+  metadata.gz: f1f27d97cda7c058c8d12c4498e30a57a9bc3899ce61aca61cb4cb5b542c4359b48e69d7a00c8867ddddc421cb561fb843039d6ac36bce4b164d9c140229e421
+  data.tar.gz: 9bca34a90ac4d1e4f15ddfb8263a0e8690aa61cb669f1519e83c43481e5e64c05133ec5317c4432b02484af66fdf2123f4574fbdb9710930bd1c0cdb94d3ed0f

data/AGENTS.md

@@ -0,0 +1,174 @@
+# AGENTS.md
+
+Instructions for coding agents. Two audiences:
+
+- **[Installing ideasbugs into a Rails app](#installing-into-a-rails-app)** — you are working in a host app and were asked to add product feedback, bug reports, or a feature-request board.
+- **[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 screenshots. The widget needs the CSRF token from `csrf_meta_tags`, which a standard Rails layout already has.
+
+If you are in a host app and this file is not in front of you, it ships inside the gem: `cat "$(bundle show ideasbugs)/AGENTS.md"`.
+
+---
+
+## Installing into a Rails app
+
+### 1. Install
+
+```bash
+bundle add ideasbugs
+bin/rails generate ideasbugs:install
+bin/rails db:migrate
+```
+
+The generator writes `config/initializers/ideasbugs.rb`, one migration (`ideasbugs_feedbacks`), and `mount_ideasbugs at: "/feedback"` into `config/routes.rb`. Note the mount path is **`/feedback`**, not `/ideasbugs`. 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 `Ideasbugs.configure do |config|` block in that initializer. Uncomment and edit in place rather than appending a second `configure` block.
+
+### 2. Wire the three things the generator cannot
+
+**a. The widget tag.** Nothing appears until this is on the page:
+
+```erb
+<%# app/views/layouts/application.html.erb, before </body> %>
+<%= ideasbugs_tag %>
+```
+
+The helper is injected into ActionView by the engine — no include, no import, no asset pipeline entry. A floating **Feedback** button appears bottom-right.
+
+**b. `authorize_admin` — do this before deploying.** The dashboard at `/feedback` defaults to **development only**. It fails closed, so shipping without this is not an open dashboard — it is a 403 reading "Forbidden. Set Ideasbugs.config.authorize_admin to grant access."
+
+Note the asymmetry, and that it is deliberate: **`enabled` defaults to everyone** (real users in production are the point of feedback collection) while **`authorize_admin` defaults to nobody outside development**.
+
+```ruby
+config.authorize_admin = ->(request) { request.env["warden"]&.user&.admin? }
+```
+
+**c. Attribution**, if the app has users. Optional, but without it every submission is anonymous.
+
+```ruby
+config.current_user = ->(request) { request.env["warden"]&.user }
+config.author_label = ->(user) { user.email }   # the short label stored + shown
+```
+
+> **`enabled`, `authorize_admin`, `current_user` and `tenant` receive the raw `request`, not a controller.** Writing `->(request) { current_user }` is the 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 middleware already set it. `author_label` is the exception: it receives whatever `current_user` returned.
+
+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
+```
+
+### 3. Verify
+
+```bash
+bin/rails routes | grep ideasbugs     # engine mounted
+bin/rails ideasbugs:seed_demo         # optional sample feedback, idempotent
+```
+
+Then in the running app: load any page, confirm the Feedback button appears, send one, and triage it at `/feedback`.
+
+### Shaping the widget
+
+```ruby
+config.kinds = %w[bug feature other]          # labels resolve through I18n (ideasbugs.kinds.<kind>)
+config.sections = ["Billing", "Dashboard"]     # [] hides the select entirely
+config.show_button = false                     # then open it from your own UI
+config.button_label = "Report a problem"       # nil = localized default
+```
+
+With `show_button = false`, any element carrying `data-ideasbugs-open` opens the form — put it in a menu, a footer, a help panel.
+
+### Screenshots
+
+`config.screenshots` is on by default but **requires Active Storage in the host app** (`rails active_storage:install`); the widget hides the upload control when it is off or Active Storage is absent, and the config exposes `screenshots_enabled?` for exactly that pair of conditions. Caps: `max_screenshots` (3), `max_screenshot_size` (5 MB), both enforced server-side. Images stream through the dashboard's own gate at `/feedback/feedbacks/:id/screenshots/:id` — **never a public blob URL**. Do not build your own blob links.
+
+### Statuses
+
+`open → in_review → resolved`, as plain strings in `Ideasbugs::Feedback::STATUSES` with a scope per status (`Feedback.open`, `.in_review`, `.resolved`) plus `newest_first`. Deliberately not an Active Record enum — `open` as an enum scope would collide with `Kernel#open`. Do not "modernize" it into an enum.
+
+### 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.customer&.to_gid&.to_s }
+```
+
+Optional sugar on a host model (`has_feedback` is available on every Active Record class already):
+
+```ruby
+class Customer < ApplicationRecord
+  has_feedback   # keyed by to_gid.to_s — must match config.tenant
+end
+customer.feedback.open
+```
+
+`bin/rails generate ideasbugs: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 copy the widget JavaScript into `app/javascript`, or add a `<script>` tag for it.** `ideasbugs_tag` renders what is needed and the engine serves the code same-origin. There is no build step and nothing for esbuild/importmap/Tailwind to know about.
+- **Do not build your own dashboard.** Use the mounted one; `config.admin_layout = "admin/application"` renders it inside an existing admin shell.
+- **Do not expose screenshots by blob URL** — the gated route exists so a leaked signed URL cannot hand over a customer's screenshot.
+- **Do not set config outside the initializer.** `rate_limit` in particular is read once when the controller class loads; assigning config per-request mutates it process-wide.
+- **Do not convert the status strings to an enum** (see above).
+
+### 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 | **Who can read the dashboard. Set before deploying.** |
+| `enabled` | everyone | Per-request gate for the widget and submissions |
+| `current_user` | `nil` | Receives the request |
+| `author_label` | email, else `to_s` | Receives the user |
+| `tenant` | `nil` | One board per tenant — see [Multi-tenancy](#multi-tenancy) |
+| `kinds` | `bug feature other` | Labels via `ideasbugs.kinds.<kind>` |
+| `sections` | `[]` | App areas as a select; empty hides it |
+| `screenshots` | `true` | Needs Active Storage; inert without it |
+| `max_screenshots`, `max_screenshot_size` | `3`, `5.megabytes` | Enforced server-side |
+| `storage_service` | app default | A `storage.yml` key for a dedicated bucket |
+| `show_button`, `button_label` | `true`, localized | `false` = open from `data-ideasbugs-open` |
+| `admin_layout` | `ideasbugs/application` | Render inside your admin shell |
+| `rate_limit` | `{ to: 10, within: 60 }` | Rails 7.2+; ignored on 7.1. `nil` disables |
+| `mount_path` | `"/feedback"` | Keep in sync with `mount_ideasbugs at:` |
+| `on_submit` | no-op | Runs inline after save — Slack, email, a ticket |
+
+### Common failure modes
+
+| Symptom | Cause |
+| --- | --- |
+| `/feedback` returns 403 "Set Ideasbugs.config.authorize_admin to grant access" | Exactly what it says: still at the development-only default |
+| No Feedback button | `ideasbugs_tag` missing from the rendered layout, `config.enabled` false, or `show_button = false` with no opener of your own |
+| Submissions rejected with an invalid-token error | The layout is missing `csrf_meta_tags` |
+| No screenshot upload control | Active Storage not installed, or `screenshots = false` |
+| `ideasbugs:tenant` fails on a duplicate column | It is an upgrade generator for pre-tenant installs; a fresh install already has the column |
+| `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 rake test:system     # browser tests, separate task
+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/` controller, model, dashboard views · `lib/ideasbugs/` config, widget JS, seeds, engine, `has_feedback` · `lib/generators/ideasbugs/` install and tenant · `config/locales/` · `test/` minitest with `test/dummy` as the host app, system tests excluded from the default task.
+
+Conventions this codebase holds to — follow them rather than the first thing that works:
+
+- **Multi-tenancy is an opaque string key, never a foreign key.** `config.tenant` returns whatever the host wants; `has_feedback` is a veneer over `Feedback.for_tenant`. No association, no `owner_type` coupling.
+- **Active Storage is optional at runtime.** `screenshots_enabled?` checks the switch *and* whether the constant is defined, so an app without Active Storage gets a working widget rather than an exception.
+- **Attachments stream through the engine's gate**, never a public blob URL.
+- **The widget is plain JS served same-origin by the engine** — no build step, no framework.
+- **The dummy app pins `config.active_job.queue_adapter = :test`.** Do not remove it or let it drift back to the `:async` default. Attaching a screenshot enqueues Active Storage's analysis job, and `:async` runs it on a background thread that checks out its own connection — writes no test transaction covers, landing in the middle of whatever runs next. That is a suite that fails order-dependently in a test which never created a row, and it is miserable to trace back.
+- Every user-facing change bumps `lib/ideasbugs/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,47 @@
 # Changelog
 
+## 0.8.0
+
+- **`config.admin_layout` now works on its own.** The dashboard's stylesheet was
+  declared in the gem's layout, so replacing that layout dropped it and the
+  dashboard rendered unstyled. It moves into the views, so every layout gets it
+  with nothing asked of the host.
+- **The dashboard stylesheet no longer claims selectors it does not own.** It
+  styled bare `*`, `body` and `a`, and its `.container`, `.card` and `.tabs` are
+  names other frameworks use too. Component rules now nest inside an
+  `.ib-dashboard` wrapper the views render, and every custom property is `--ib-`
+  prefixed — that collision ran both ways, so a host defining `--bg` recoloured
+  the dashboard just as easily.
+- **Added `config.base_controller_class`.** Name the controller your own admin
+  inherits from and the dashboard adopts its layout, helpers, authentication and
+  request context. Default is unchanged.
+- **`create` moved to `Ideasbugs::SubmissionsController`.** One controller served
+  both the widget's write endpoint and the triage actions, so
+  `base_controller_class` would have put staff authentication in front of every
+  bug report. `POST /feedbacks` now routes there; the URL is unchanged. If you
+  referenced `Ideasbugs::FeedbacksController#create`, that is the breaking change
+  in this release. The per-IP rate limiter moved with the action.
+- **Migrations follow the host's `primary_key_type`,** the same
+  `Rails.configuration.generators` lookup Rails' own Active Storage migration
+  does. A uuid-keyed app has a uuid `active_storage_attachments.record_id`, so a
+  bigint table here could never hold a screenshot: `attach` raised
+  `NotNullViolation`. A host that set nothing gets an identical migration.
+- A `BackboneTest` now fails the build on any of the above regressing.
+
+## 0.7.8
+
+- Adds `AGENTS.md`: install and integration instructions written for coding
+  agents — the request-shaped config lambdas, the `/feedback` mount path, why
+  the status strings are not an enum, and the mistakes agents actually make. It
+  ships inside the gem, so `cat "$(bundle show ideasbugs)/AGENTS.md"` works from
+  a host app.
+- The dummy app pins `queue_adapter = :test` for the test suite. Attaching a
+  screenshot enqueues Active Storage's analysis job, and the default `:async`
+  adapter runs it on a background thread with its own database connection —
+  writes no test transaction covers, which is how a suite starts failing
+  order-dependently in a test that never created a row. No effect on the gem
+  itself.
+
 ## 0.7.7 (2026-08-01)
 
 - Added `Ideasbugs::Seeds.load!` and a `rake ideasbugs:seed_demo` task that

data/README.md

@@ -64,6 +64,11 @@ duplicating them.
 Ruby >= 3.2 · Rails >= 7.1 · Active Storage only if you want screenshots ·
 CSRF token comes from `csrf_meta_tags`, already in a standard Rails layout.
 
+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 ideasbugs)/AGENTS.md"` works from any app that bundles it.
+
 ## What you get
 
 |              |                                                                          |
@@ -97,6 +102,8 @@ Everything is optional — a fresh install works with zero config. In
 | Option                | Default                     | What it does                                        |
 | --------------------- | --------------------------- | --------------------------------------------------- |
 | `authorize_admin`     | development only            | **Who can read the dashboard.** Override before deploying |
+| `base_controller_class` | `ActionController::Base` | Controller the dashboard inherits — name your admin's and it adopts its layout, helpers and auth |
+| `admin_layout`        | the gem's own               | Just the shell, if you don't want the whole controller |
 | `enabled`             | everyone                    | Who can send feedback. `false` hides the widget and rejects posts |
 | `current_user`        | `nil`                       | Attribute a submission to a user. Receives the request |
 | `author_label`        | the user's `email`          | Short label stored and shown in the dashboard        |

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ideasbugs
+  # Who is asking, which tenant they are in, and the gates that answer both.
+  #
+  # A concern rather than inherited behaviour because the engine has two
+  # controller roots: the public endpoints hang off ActionController::Base, and
+  # the dashboard hangs off whatever the host set as `base_controller_class`.
+  module RequestContext
+    extend ActiveSupport::Concern
+
+    private
+
+    def ideasbugs_admin_layout
+      Ideasbugs.config.admin_layout
+    end
+
+    def current_author
+      return @current_author if defined?(@current_author)
+
+      @current_author = Ideasbugs.config.current_user.call(request)
+    end
+
+    # The tenant for this request (nil = the single global board). Every read
+    # and write scopes to it, so a resolved-tenant admin only ever sees and
+    # writes their own tenant's feedback.
+    def current_tenant
+      return @current_tenant if defined?(@current_tenant)
+
+      @current_tenant = Ideasbugs.tenant(request)
+    end
+
+    def require_enabled
+      head :forbidden unless Ideasbugs.enabled?(request)
+    end
+
+    # Server-side gate for the dashboard. Default: development only.
+    def require_admin
+      return if Ideasbugs.admin?(request)
+
+      render plain: 'Forbidden. Set Ideasbugs.config.authorize_admin to grant access.',
+             status: :forbidden
+    end
+
+    # Every dashboard query starts here, so an admin can only ever load,
+    # triage, or delete feedback in their own tenant — a cross-tenant id 404s.
+    def tenant_scope
+      Feedback.for_tenant(current_tenant)
+    end
+  end
+end

data/app/controllers/ideasbugs/application_controller.rb

@@ -1,28 +1,16 @@
 # frozen_string_literal: true
 
 module Ideasbugs
+  # Root of the engine's PUBLIC surface: widget.js and the submission endpoint.
+  # These stay on a plain ActionController::Base deliberately — someone filing a
+  # bug report must not be routed through a host's admin controller, which would
+  # demand a staff session for the widget.
+  #
+  # The dashboard's root is DashboardController, and that is where
+  # `config.base_controller_class` applies.
   class ApplicationController < ActionController::Base
-    protect_from_forgery with: :exception
-
-    private
-
-    def ideasbugs_admin_layout
-      Ideasbugs.config.admin_layout
-    end
-
-    def current_author
-      return @current_author if defined?(@current_author)
+    include RequestContext
 
-      @current_author = Ideasbugs.config.current_user.call(request)
-    end
-
-    # The tenant for this request (nil = the single global board). Every read
-    # and write scopes to it, so a resolved-tenant admin only ever sees and
-    # writes their own tenant's feedback.
-    def current_tenant
-      return @current_tenant if defined?(@current_tenant)
-
-      @current_tenant = Ideasbugs.tenant(request)
-    end
+    protect_from_forgery with: :exception
   end
 end

data/app/controllers/ideasbugs/dashboard_controller.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ideasbugs
+  # Root of the STAFF surface: the triage queue and the screenshot proxy.
+  #
+  # Inherits from `config.base_controller_class` — by default a plain
+  # ActionController::Base, which is why `authorize_admin` exists. Point it at
+  # the controller your own admin already inherits from and the dashboard picks
+  # up that stack wholesale: your layout, your helpers, your authentication, and
+  # whatever request context your before_actions establish.
+  #
+  # Only the dashboard hangs off it. The widget's endpoint stays on
+  # ApplicationController, so wiring an admin base controller here can never
+  # demand a staff session from someone filing a report.
+  class DashboardController < Ideasbugs.base_controller
+    include RequestContext
+
+    # A host base controller brings its own layout, and declaring one here would
+    # override it. So the gem only claims the layout when it owns the decision:
+    # no host base controller, or a host that named an `admin_layout` explicitly.
+    layout :ideasbugs_admin_layout unless superclass != ActionController::Base &&
+                                          Ideasbugs.config.admin_layout == Configuration::DEFAULT_ADMIN_LAYOUT
+
+    before_action :require_admin
+
+    # A host base controller has configured CSRF already; declaring it twice
+    # would run the check twice.
+    protect_from_forgery with: :exception if superclass == ActionController::Base
+  end
+end

data/app/controllers/ideasbugs/feedbacks_controller.rb

@@ -1,27 +1,12 @@
 # frozen_string_literal: true
 
 module Ideasbugs
-  class FeedbacksController < ApplicationController
+  class FeedbacksController < DashboardController
     PER_PAGE = 50
 
-    layout :ideasbugs_admin_layout, except: :create
-
     # The widget posts here; everything else is the triage dashboard.
-    before_action :require_enabled, only: :create
-    before_action :require_admin, except: :create
     before_action :set_feedback, only: %i[show update destroy]
 
-    # Throttle the public endpoint per IP so one user or bot can't flood the
-    # table (each submission may carry megabytes of screenshots). Uses the
-    # rate limiter built into Rails 7.2+ (backed by Rails.cache); on Rails 7.1
-    # this is a no-op. Tune or disable via config.rate_limit — read once at
-    # boot, after the host's initializer.
-    if respond_to?(:rate_limit) && Ideasbugs.config.rate_limit
-      rate_limit(**Ideasbugs.config.rate_limit,
-                 only: :create,
-                 with: -> { render json: { errors: [t_error(:error_rate_limited)] }, status: :too_many_requests })
-    end
-
     def index
       @status = Feedback::STATUSES.include?(params[:status]) ? params[:status] : 'open'
       @kind = Ideasbugs.config.kinds.map(&:to_s).include?(params[:kind]) ? params[:kind] : nil
@@ -46,23 +31,6 @@ module Ideasbugs
 
     def show; end
 
-    def create
-      feedback = Feedback.new(feedback_params)
-      feedback.user_agent = request.user_agent
-      feedback.tenant = current_tenant
-      attribute_author(feedback)
-
-      error = attach_screenshots(feedback)
-      return render json: { errors: [error] }, status: :unprocessable_entity if error
-
-      if feedback.save
-        notify_host(feedback)
-        head :created
-      else
-        render json: { errors: feedback.errors.full_messages }, status: :unprocessable_entity
-      end
-    end
-
     def update
       @feedback.update!(params.require(:feedback).permit(:status))
       redirect_back fallback_location: feedback_path(@feedback), status: :see_other
@@ -75,28 +43,10 @@ module Ideasbugs
 
     private
 
-    def require_enabled
-      head :forbidden unless Ideasbugs.enabled?(request)
-    end
-
-    # Server-side gate for the dashboard. Default: development only.
-    def require_admin
-      return if Ideasbugs.admin?(request)
-
-      render plain: 'Forbidden. Set Ideasbugs.config.authorize_admin to grant access.',
-             status: :forbidden
-    end
-
     def set_feedback
       @feedback = tenant_scope.find(params[:id])
     end
 
-    # Every dashboard query starts here, so an admin can only ever load,
-    # triage, or delete feedback in their own tenant — a cross-tenant id 404s.
-    def tenant_scope
-      Feedback.for_tenant(current_tenant)
-    end
-
     # Case-insensitive match on the free-text columns. LOWER() keeps it
     # portable across SQLite/PostgreSQL/MySQL, and the explicit ESCAPE makes
     # the sanitized backslash escapes work on SQLite, which has no default
@@ -109,62 +59,5 @@ module Ideasbugs
         q: pattern
       )
     end
-
-    # The host's hook must never turn a saved submission into a 500 — the
-    # feedback is in the database; notification failures are the host's logs'
-    # problem.
-    def notify_host(feedback)
-      Ideasbugs.config.on_submit.call(feedback)
-    rescue StandardError => e
-      Rails.logger.error("ideasbugs: on_submit hook raised #{e.class}: #{e.message}")
-    end
-
-    def feedback_params
-      params.require(:feedback).permit(:kind, :section, :message, :page_url)
-    end
-
-    def attribute_author(feedback)
-      author = current_author
-      return unless author
-
-      feedback.author_id = author.id.to_s if author.respond_to?(:id)
-      feedback.author_label = Ideasbugs.config.author_label.call(author)
-    end
-
-    # Validates and attaches uploads. Returns an error message, or nil when
-    # everything (including "no screenshots at all") is fine.
-    def attach_screenshots(feedback)
-      files = Array(params.dig(:feedback, :screenshots)).reject(&:blank?)
-      return nil if files.empty?
-      return t_error(:error_save) unless Ideasbugs.config.screenshots_enabled?
-      return t_error(:error_too_many, count: Ideasbugs.config.max_screenshots) if too_many?(files)
-      return t_error(:error_too_large, size: max_size_mb) if files.any? { |f| f.size > max_size }
-      return t_error(:error_save) unless files.all? { |f| f.content_type.to_s.start_with?('image/') }
-
-      feedback.screenshots.attach(files)
-      nil
-    end
-
-    def too_many?(files)
-      files.size > Ideasbugs.config.max_screenshots
-    end
-
-    def max_size
-      Ideasbugs.config.max_screenshot_size
-    end
-
-    def max_size_mb
-      max_size / (1024 * 1024)
-    end
-
-    def t_error(key, **args)
-      defaults = {
-        error_save: 'Could not send feedback. Please try again.',
-        error_too_many: 'Too many screenshots (max %{count}).',
-        error_too_large: 'A screenshot is too large (max %{size} MB).',
-        error_rate_limited: 'Too many submissions. Please wait a moment and try again.'
-      }
-      I18n.t(key, scope: :ideasbugs, default: defaults[key], **args)
-    end
   end
 end

data/app/controllers/ideasbugs/screenshots_controller.rb

@@ -6,9 +6,7 @@ module Ideasbugs
   # screenshots can contain anything a user's screen showed, so they must never
   # be reachable without passing the same gate as the dashboard — regardless of
   # how the host app configures (or doesn't configure) blob access.
-  class ScreenshotsController < ApplicationController
-    before_action :require_admin
-
+  class ScreenshotsController < DashboardController
     def show
       screenshot = Feedback.for_tenant(current_tenant)
                            .find(params[:feedback_id]).screenshots.find(params[:id])

data/app/controllers/ideasbugs/submissions_controller.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Ideasbugs
+  # The widget's write endpoint: POST /feedbacks.
+  #
+  # Public, so it stays on ApplicationController and never inherits a host's
+  # admin base controller — someone filing a bug report must not be asked for a
+  # staff session. The triage actions live in FeedbacksController, which does
+  # inherit it.
+  class SubmissionsController < ApplicationController
+    before_action :require_enabled
+
+    # Throttle the public endpoint per IP so one user or bot can't flood the
+    # table (each submission may carry megabytes of screenshots). Uses the
+    # rate limiter built into Rails 7.2+ (backed by Rails.cache); on Rails 7.1
+    # this is a no-op. Tune or disable via config.rate_limit — read once at
+    # boot, after the host's initializer.
+    if respond_to?(:rate_limit) && Ideasbugs.config.rate_limit
+      rate_limit(**Ideasbugs.config.rate_limit,
+                 only: :create,
+                 with: -> { render json: { errors: [t_error(:error_rate_limited)] }, status: :too_many_requests })
+    end
+
+    def create
+      feedback = Feedback.new(feedback_params)
+      feedback.user_agent = request.user_agent
+      feedback.tenant = current_tenant
+      attribute_author(feedback)
+
+      error = attach_screenshots(feedback)
+      return render json: { errors: [error] }, status: :unprocessable_entity if error
+
+      if feedback.save
+        notify_host(feedback)
+        head :created
+      else
+        render json: { errors: feedback.errors.full_messages }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    # The host's hook must never turn a saved submission into a 500 — the
+    # feedback is in the database; notification failures are the host's logs'
+    # problem.
+    def notify_host(feedback)
+      Ideasbugs.config.on_submit.call(feedback)
+    rescue StandardError => e
+      Rails.logger.error("ideasbugs: on_submit hook raised #{e.class}: #{e.message}")
+    end
+
+    def feedback_params
+      params.require(:feedback).permit(:kind, :section, :message, :page_url)
+    end
+
+    def attribute_author(feedback)
+      author = current_author
+      return unless author
+
+      feedback.author_id = author.id.to_s if author.respond_to?(:id)
+      feedback.author_label = Ideasbugs.config.author_label.call(author)
+    end
+
+    # Validates and attaches uploads. Returns an error message, or nil when
+    # everything (including "no screenshots at all") is fine.
+    def attach_screenshots(feedback)
+      files = Array(params.dig(:feedback, :screenshots)).reject(&:blank?)
+      return nil if files.empty?
+      return t_error(:error_save) unless Ideasbugs.config.screenshots_enabled?
+      return t_error(:error_too_many, count: Ideasbugs.config.max_screenshots) if too_many?(files)
+      return t_error(:error_too_large, size: max_size_mb) if files.any? { |f| f.size > max_size }
+      return t_error(:error_save) unless files.all? { |f| f.content_type.to_s.start_with?('image/') }
+
+      feedback.screenshots.attach(files)
+      nil
+    end
+
+    def too_many?(files)
+      files.size > Ideasbugs.config.max_screenshots
+    end
+
+    def max_size_mb
+      max_size / (1024 * 1024)
+    end
+
+    def max_size
+      Ideasbugs.config.max_screenshot_size
+    end
+
+    def t_error(key, **args)
+      defaults = {
+        error_save: 'Could not send feedback. Please try again.',
+        error_too_many: 'Too many screenshots (max %{count}).',
+        error_too_large: 'A screenshot is too large (max %{size} MB).',
+        error_rate_limited: 'Too many submissions. Please wait a moment and try again.'
+      }
+      I18n.t(key, scope: :ideasbugs, default: defaults[key], **args)
+    end
+  end
+end