dispatch-rails 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 300eb860cc2bb5f7dff2322818cc6bd552507695c71c84c9be81ccbd6e34a3fd
+  data.tar.gz: 4070748d3d36256a456e9eb960d36c47418ec55f699e0984a9fd49c4d67b501f
+SHA512:
+  metadata.gz: 1dcbd3e9a81c078086e62e5e50bca81679832a2dff5e5fd1fe5b4a82bc052e445adb83dbc8e1f7c22b8699e94d6a7d5a6d843d2ae7f974a97cabf682289d767d
+  data.tar.gz: 21765b8506a454e84d225b8d932ce6a15dc2cddd948d8247cddae59908cfe1499139f607a90892e1dffa247a299f156b3c09e1100a73efeb2ae8243af9a7a133

data/README.md

@@ -0,0 +1,227 @@
+# dispatch-rails
+
+Feed [Dispatch](https://dispatchit.app), the AI-native ticketing system, from any
+Rails app. Two ways in:
+
+- **API-only / Errors** — headless server-side exception tracking for apps with no
+  UI (API services, background workers). No widget; just automatic capture,
+  structured error responses, and a programmatic report helper.
+- **Widget** — a floating 💬 feedback button for apps that have a UI, where a
+  human reports a bug, requests a feature, or suggests a change, and the
+  report ships with browser context.
+
+Both modes authenticate with the same project API token and share the same error
+pipeline.
+
+## Install
+
+```ruby
+# Gemfile
+gem "dispatch-rails", "~> 0.6"
+```
+
+---
+
+## API-only / Errors mode
+
+For an app with no UI, set `mode: :errors_only`. Server-side capture is on by
+default once configured — a Rack middleware catches unhandled request exceptions
+(with full request + user context) and a `Rails.error` subscriber catches
+background/job errors. The widget and browser-error tags become no-ops.
+
+```ruby
+# config/initializers/dispatch.rb
+Dispatch::Rails.configure do |c|
+  c.mode     = :errors_only
+  c.api_key  = Rails.application.credentials.dig(:dispatch, :api_key)
+  c.endpoint = "https://dispatchit.app/api/v1/tickets"  # host is also used to derive the error + report URLs
+  c.release  = ENV["GIT_SHA"]
+  c.enabled_environments = %w[production staging]
+
+  # Resolve the affected user from your API auth (see "Identity" below).
+  c.user    = ->(ctx) { ctx.request.env["warden"]&.user&.then { { email: _1.email, external_id: _1.id } } }
+  c.context = ->(ctx) { { request_id: ctx.request.request_id }.compact }
+
+  # Structured error responses (opt-in).
+  c.structured_error_responses = true
+  c.annotate_error_body        = false  # headers only by default; true also merges into JSON error bodies
+end
+```
+
+### Identity (the contract that matters for API apps)
+
+The `user` and `context` lambdas receive the **controller instance** (not a
+session). That's the seam for API auth — read whatever identifies the caller:
+
+```ruby
+c.user = ->(ctx) {
+  u = ctx.try(:current_user) ||
+      ctx.request.env["warden"]&.user ||
+      ((k = ctx.request.headers["X-API-Key"]) && User.find_by(api_key: k))
+  u && { email: u.email, external_id: u.id }
+}
+c.context = ->(ctx) { { player_id: ctx.request.headers["X-Player-ID"] }.compact }
+```
+
+`context` returns extra tags merged into every event (your explicit `context[:tags]`
+on a manual capture still win). For background-job errors there is no controller,
+so both lambdas receive `nil` — guard accordingly.
+
+### What's captured
+
+Each event is a Sentry-shaped payload: the exception chain with source context for
+in-app frames, `transaction` (`controller#action`), `tags.request_id` (the Rails
+request id), the request URL/method/headers, the resolved user, and your `context`
+tags. Request params are **off by default**; opt in with `c.send_default_params = true`
+(uses Rails' `filtered_parameters`, so your `config.filter_parameters` redactions
+apply — add a `before_send` for stricter scrubbing).
+
+### Process lifecycle (boot crashes, rake failures, shutdown flush)
+
+Errors that never reach the Rack stack are still captured:
+
+- **Crash at exit** — an unhandled exception that kills the process (a boot
+  crash in an initializer, a dying `rails runner` script) is reported from an
+  `at_exit` hook, tagged `source: at_exit`. Normal exits and SIGTERM-driven
+  graceful shutdowns are ignored.
+- **Rake task failures** — rake rescues the real exception itself, so the gem
+  patches `Rake::Application#display_error_message` and reports the failure
+  tagged `source: rake` with the failing command.
+- **Shutdown flush** — events are sent from a background queue; on process
+  exit the in-progress traffic-heartbeat window is shipped and the queue is
+  drained (up to `shutdown_timeout` seconds) so restarts and deploys don't
+  drop reports — or the final window of confound-guard counts — captured
+  moments earlier.
+
+```ruby
+c.capture_at_exit  = true  # default; set false to skip the crash-at-exit report
+c.shutdown_timeout = 3     # seconds to wait for the send queue to drain at exit; 0 skips
+```
+
+### Traffic heartbeats (confound signal)
+
+On by default in enabled environments, the SDK ships lightweight per-`transaction`
+request/error counts — one small aggregate POST per minute, regardless of request
+volume. Dispatch uses these so fix verification can tell *"the error stopped because
+we fixed it"* from *"…because nobody hits that path anymore"*: a fix is only marked
+verified if the affected `controller#action` is still serving successful traffic.
+
+```ruby
+c.capture_traffic        = true   # default; set false to disable
+c.traffic_sample_rate    = 1.0    # independent of error_sample_rate
+c.heartbeat_flush_seconds = 60    # aggregation window
+```
+
+No request bodies, params, or user data are sent — only counts keyed by
+`controller#action`.
+
+### Structured error responses
+
+With `c.structured_error_responses = true`, any 4xx/5xx response carries:
+
+- `X-Dispatch-Request-Id: <request id>` — the correlation key
+- `X-Dispatch-Report-Url: <link>` — informational
+
+This is the API-only analogue of the widget: it hands the caller an id they can
+quote. With `c.annotate_error_body = true`, the same fields (`dispatch_request_id`,
+`dispatch_report_url`) are merged into JSON error bodies too (RFC 7807-friendly —
+they sit beside `type`/`title`/`detail`). The middleware never changes status codes
+and passes through anything it can't safely parse.
+
+### Curated reports (programmatic / agent)
+
+A consumer (or an AI agent inside your app) turns a failure into a tracked report:
+
+```ruby
+Dispatch::Rails.report(
+  description: "Nightly import aborted: upstream returned 502",
+  severity: "high",
+  correlation_id: request.request_id,   # links to the captured error
+  metadata: { job: "ImportJob" }
+)
+# => { "id" => 123, "status" => "inbox", "url" => "https://acme.dispatchit.app/tickets/123" }
+```
+
+Or over HTTP, quoting the id from `X-Dispatch-Request-Id`:
+
+```bash
+curl -X POST https://dispatchit.app/api/v1/tickets \
+  -H "Authorization: Bearer dsp_live_…" -H "Content-Type: application/json" \
+  -d '{"ticket":{"description":"Checkout 500s on empty cart","severity":"high",
+        "source":"api","metadata":{"correlation_id":"abc123"}}}'
+```
+
+Dispatch links the resulting ticket to the captured error's group. (An MCP server /
+CLI wrapping this is a planned agent-workflow extension.)
+
+### Manual capture
+
+```ruby
+rescue => e
+  Dispatch::Rails.capture_exception(e, context: { tags: { area: "import" } })
+end
+```
+
+### Not on Rails?
+
+Any language with a Sentry SDK can point at Dispatch via a DSN — see
+[docs/sentry-dsn.md](docs/sentry-dsn.md).
+
+---
+
+## Widget mode
+
+For apps with a UI. Configure, then render the widget in your layout:
+
+```ruby
+# config/initializers/dispatch.rb
+Dispatch::Rails.configure do |c|
+  c.api_key  = Rails.application.credentials.dig(:dispatch, :api_key)
+  c.endpoint = "https://dispatchit.app/api/v1/tickets"
+  c.user     = ->(ctx) { ctx.current_user&.then { { email: _1.email, external_id: _1.id } } }
+  c.metadata = ->(ctx) { { release: ENV["GIT_SHA"], env: Rails.env } }
+end
+```
+
+```erb
+<%# In your layout, e.g. on staging %>
+<% if Rails.env.staging? %>
+  <%= dispatch_widget_tag %>
+<% end %>
+```
+
+### Per-page severity / labels
+
+```erb
+<%= dispatch_widget_tag severity: :critical, labels: %w[checkout payments] %>
+```
+
+These attach to every report from that page (`ticket.severity`, `metadata.labels`).
+
+### What the widget captures
+
+- `location.href`, `navigator.userAgent`, viewport size, `document.referrer`
+- **User path** — the last 5 things the user clicked, as `metadata.user_path`
+  (`c.capture_clicks = true`, the default)
+- Optional: last 20 `console.error` entries (`c.capture_console = true`)
+- Whatever your `user` and `metadata` lambdas return, plus per-tag severity/labels
+
+It `POST`s to your `endpoint` with `Authorization: Bearer <api_key>`, an
+auto-generated `Idempotency-Key`, and `{ ticket: { description, source: "widget",
+severity, reporter, metadata } }`.
+
+### Browser exception tracking
+
+Add the tracker to your layout `<head>` to capture uncaught JS errors and
+unhandled promise rejections (same project key, same `user` lambda for the
+affected-user email loop):
+
+```erb
+<%= dispatch_error_tracker_tag %>
+```
+
+## Multiple projects per app
+
+Each Dispatch project has its own API key. To send reports from different surfaces
+to different projects, create multiple initializers or wrap
+`Dispatch::Rails.configuration.api_key` with a per-request override.

data/app/assets/javascripts/dispatch/error_tracker.js

@@ -0,0 +1,152 @@
+// Dispatch browser error tracker. Captures uncaught errors and unhandled promise
+// rejections, builds a Sentry-shaped event, and ships it to the Dispatch ingest
+// endpoint. Plain module (not Stimulus) so it installs its handlers immediately.
+
+(function () {
+  var el = document.getElementById("dispatch-error-config");
+  var cfg = el ? safeParse(el.textContent) : window.__dispatchErrorConfig;
+  if (!cfg || !cfg.endpoint || !cfg.apiKey) return;
+  if (window.__dispatchErrorTrackerLoaded) return;
+  window.__dispatchErrorTrackerLoaded = true;
+
+  var MAX_CRUMBS = 30;
+  var breadcrumbs = [];
+
+  function safeParse(s) { try { return JSON.parse(s); } catch (e) { return null; } }
+  function now() { return Date.now() / 1000; }
+  function crumb(c) { breadcrumbs.push(c); if (breadcrumbs.length > MAX_CRUMBS) breadcrumbs.shift(); }
+
+  function uuid() {
+    if (window.crypto && crypto.randomUUID) return crypto.randomUUID().replace(/-/g, "");
+    return (Date.now().toString(16) + Math.random().toString(16).slice(2) + "0".repeat(32)).slice(0, 32);
+  }
+
+  // A short, human-readable label for a clicked element (used for breadcrumbs
+  // and the "user path" — the last few things the user clicked).
+  function describeClickTarget(node) {
+    var el = node && node.nodeType === 1 ? node : null;
+    if (!el) return null;
+    if (el.closest) {
+      el = el.closest("button, a, input, select, textarea, label, [role='button'], [role='link'], [data-action]") || el;
+    }
+    var tag = (el.tagName || "").toLowerCase();
+    var text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 40);
+    var attr = el.getAttribute &&
+      (el.getAttribute("aria-label") || el.getAttribute("title") || el.getAttribute("name") || el.getAttribute("placeholder"));
+    var id = el.id ? "#" + el.id : "";
+    var label = text || attr;
+    if (label) return (tag + id + ' "' + label + '"').slice(0, 80);
+    var cls = (typeof el.className === "string" && el.className.trim()) ? "." + el.className.trim().split(/\s+/)[0] : "";
+    return (tag + id + cls).slice(0, 80) || tag || null;
+  }
+
+  // The last few clicks, oldest→newest — a concise path to the error.
+  function userPath() {
+    return breadcrumbs
+      .filter(function (b) { return b.category === "ui.click"; })
+      .slice(-5)
+      .map(function (b) { return b.message; });
+  }
+
+  // Breadcrumbs: clicks, navigation, console.error.
+  if (cfg.captureClicks !== false) {
+    document.addEventListener("click", function (e) {
+      var label = describeClickTarget(e.target);
+      if (label) crumb({ timestamp: now(), category: "ui.click", level: "info", message: label });
+    }, true);
+  }
+
+  var origConsoleError = console.error;
+  console.error = function () {
+    try {
+      crumb({ timestamp: now(), category: "console", level: "error",
+              message: Array.prototype.map.call(arguments, String).join(" ").slice(0, 500) });
+    } finally { origConsoleError.apply(console, arguments); }
+  };
+
+  function parseStack(stack) {
+    if (!stack) return [];
+    var frames = [];
+    stack.split("\n").forEach(function (line) {
+      var m = line.match(/at\s+(.*?)\s+\((.*?):(\d+):(\d+)\)/) ||
+              line.match(/at\s+(.*?):(\d+):(\d+)/) ||
+              line.match(/(.*?)@(.*?):(\d+):(\d+)/);
+      if (!m) return;
+      var fn, url, ln, col;
+      if (m.length === 5) { fn = m[1]; url = m[2]; ln = m[3]; col = m[4]; }
+      else { fn = "?"; url = m[1]; ln = m[2]; col = m[3]; }
+      frames.push({
+        function: fn, filename: url, abs_path: url,
+        lineno: parseInt(ln, 10), colno: parseInt(col, 10),
+        in_app: url.indexOf("node_modules") === -1 && url.indexOf("http") === 0
+      });
+    });
+    return frames.reverse(); // oldest first, Sentry-style
+  }
+
+  function buildEvent(type, value, stack) {
+    return {
+      event_id: uuid(),
+      timestamp: now(),
+      platform: "javascript",
+      level: "error",
+      environment: cfg.environment,
+      release: cfg.release,
+      exception: { values: [{
+        type: type || "Error",
+        value: String(value == null ? "" : value).slice(0, 2000),
+        mechanism: { type: "onerror", handled: false },
+        stacktrace: { frames: parseStack(stack) }
+      }] },
+      breadcrumbs: { values: breadcrumbs.slice() },
+      user_path: userPath(),
+      request: { url: location.href, headers: { "User-Agent": navigator.userAgent } },
+      user: cfg.user || null,
+      tags: cfg.tags || {}
+    };
+  }
+
+  function sampledOut() {
+    var rate = cfg.sampleRate == null ? 1 : cfg.sampleRate;
+    return Math.random() > rate;
+  }
+
+  function send(event) {
+    if (sampledOut()) return;
+    var body = JSON.stringify(event);
+    // Preferred: fetch keepalive (proper CORS + Authorization header).
+    if (window.fetch) {
+      try {
+        fetch(cfg.endpoint, {
+          method: "POST", keepalive: true, mode: "cors",
+          headers: { "Content-Type": "application/json", "Authorization": "Bearer " + cfg.apiKey },
+          body: body
+        });
+        return;
+      } catch (e) { /* fall through */ }
+    }
+    // Fallback for unload: sendBeacon can't set headers, so use ?sentry_key=.
+    if (navigator.sendBeacon) {
+      var url = cfg.endpoint + (cfg.endpoint.indexOf("?") >= 0 ? "&" : "?") + "sentry_key=" + encodeURIComponent(cfg.apiKey);
+      try { navigator.sendBeacon(url, new Blob([body], { type: "application/json" })); } catch (e) { /* noop */ }
+    }
+  }
+
+  window.addEventListener("error", function (e) {
+    var err = e.error;
+    send(buildEvent(err && err.name, (err && err.message) || e.message, err && err.stack));
+  });
+
+  window.addEventListener("unhandledrejection", function (e) {
+    var r = e.reason || {};
+    var value = r.message || (typeof e.reason === "string" ? e.reason : "Unhandled promise rejection");
+    send(buildEvent(r.name || "UnhandledRejection", value, r.stack));
+  });
+
+  // Manual capture API: window.Dispatch.captureException(error)
+  window.Dispatch = window.Dispatch || {};
+  window.Dispatch.captureException = function (err) {
+    err = err || {};
+    send(buildEvent(err.name, err.message, err.stack));
+  };
+})();

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

@@ -0,0 +1,293 @@
+// Dispatch widget Stimulus controller.
+// Registered automatically if Stimulus is present on the host page.
+
+import { Controller } from "@hotwired/stimulus";
+
+const CONSOLE_CAPTURE_MAX = 20;
+const CLICK_PATH_MAX = 5;
+const WIDGET_VERSION = "0.3.0";
+const MAX_SCREENSHOTS = 5;
+const MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+const SCREENSHOT_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+
+// A short, human-readable label for an element the user clicked — used to build
+// the "user path" (the last few things they clicked before reporting).
+function describeClickTarget(node) {
+  let el = node && node.nodeType === 1 ? node : null;
+  if (!el) return null;
+  if (el.closest) {
+    el = el.closest("button, a, input, select, textarea, label, [role='button'], [role='link'], [data-action]") || el;
+  }
+  const tag = (el.tagName || "").toLowerCase();
+  const text = (el.innerText || el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 40);
+  const attr = el.getAttribute &&
+    (el.getAttribute("aria-label") || el.getAttribute("title") || el.getAttribute("name") || el.getAttribute("placeholder"));
+  const id = el.id ? "#" + el.id : "";
+  const label = text || attr;
+  if (label) return (tag + id + ' "' + label + '"').slice(0, 80);
+  const cls = (typeof el.className === "string" && el.className.trim()) ? "." + el.className.trim().split(/\s+/)[0] : "";
+  return (tag + id + cls).slice(0, 80) || tag || null;
+}
+
+export default class DispatchWidgetController extends Controller {
+  static targets = [
+    "button", "modal", "description", "error", "submit", "toast",
+    "fileInput", "dropzone", "previews", "attachButton"
+  ];
+  static values = {
+    endpoint: String,
+    apiKey: String,
+    user: { type: Object, default: {} },
+    metadata: { type: Object, default: {} },
+    severity: { type: String, default: "" },
+    captureConsole: Boolean,
+    captureClicks: Boolean
+  };
+
+  connect() {
+    this.files = [];
+    this.consoleEntries = [];
+    this.clickPath = [];
+    if (this.captureConsoleValue) {
+      const original = console.error;
+      console.error = (...args) => {
+        try {
+          this.consoleEntries.push(args.map(String).join(" "));
+          if (this.consoleEntries.length > CONSOLE_CAPTURE_MAX) {
+            this.consoleEntries.shift();
+          }
+        } finally {
+          original.apply(console, args);
+        }
+      };
+    }
+    if (this.captureClicksValue) {
+      this.boundTrackClick = this.trackClick.bind(this);
+      document.addEventListener("click", this.boundTrackClick, true);
+    }
+  }
+
+  disconnect() {
+    if (this.boundTrackClick) {
+      document.removeEventListener("click", this.boundTrackClick, true);
+    }
+  }
+
+  // Record the last few non-widget clicks as the user's path to the report.
+  trackClick(event) {
+    const target = event.target;
+    if (target && target.closest && target.closest("[data-controller~='dispatch-widget']")) return;
+    const label = describeClickTarget(target);
+    if (!label) return;
+    this.clickPath.push(label);
+    if (this.clickPath.length > CLICK_PATH_MAX) this.clickPath.shift();
+  }
+
+  open() {
+    this.modalTarget.hidden = false;
+    this.descriptionTarget.focus();
+  }
+
+  close() {
+    this.modalTarget.hidden = true;
+    this.errorTarget.style.display = "none";
+    this.descriptionTarget.value = "";
+    this.files = [];
+    this.renderPreviews();
+  }
+
+  // --- Screenshot input: file picker, drag & drop, paste --------------------
+
+  openFilePicker() {
+    this.fileInputTarget.click();
+  }
+
+  filesPicked(event) {
+    this.addFiles(event.target.files);
+    event.target.value = ""; // allow re-picking the same file
+  }
+
+  dragover(event) {
+    event.preventDefault();
+    this.dropzoneTarget.style.borderColor = "#2563eb";
+  }
+
+  dragleave() {
+    this.dropzoneTarget.style.borderColor = "#1f2937";
+  }
+
+  drop(event) {
+    event.preventDefault();
+    this.dropzoneTarget.style.borderColor = "#1f2937";
+    if (event.dataTransfer && event.dataTransfer.files.length) {
+      this.addFiles(event.dataTransfer.files);
+    }
+  }
+
+  paste(event) {
+    const items = event.clipboardData && event.clipboardData.items;
+    if (!items) return;
+    const pasted = [];
+    for (const item of items) {
+      if (item.kind === "file") {
+        const file = item.getAsFile();
+        if (file) pasted.push(file);
+      }
+    }
+    if (pasted.length) {
+      event.preventDefault();
+      this.addFiles(pasted);
+    }
+  }
+
+  async addFiles(fileList) {
+    for (const file of Array.from(fileList)) {
+      if (this.files.length >= MAX_SCREENSHOTS) {
+        this.showError(`You can attach at most ${MAX_SCREENSHOTS} screenshots.`);
+        break;
+      }
+      if (!SCREENSHOT_TYPES.includes(file.type)) {
+        this.showError("Screenshots must be PNG, JPEG, GIF, or WebP images.");
+        continue;
+      }
+      if (file.size > MAX_SCREENSHOT_BYTES) {
+        this.showError("Each screenshot must be smaller than 5 MB.");
+        continue;
+      }
+      const name = file.name || "screenshot.png";
+      if (this.files.some((f) => f.filename === name && f.size === file.size)) {
+        continue; // skip duplicates
+      }
+      const dataUrl = await this.readAsDataURL(file);
+      this.files.push({
+        filename: name,
+        content_type: file.type,
+        data: dataUrl.split(",")[1] || "",
+        size: file.size,
+        preview: dataUrl
+      });
+      this.renderPreviews();
+    }
+  }
+
+  removeFile(index) {
+    this.files.splice(index, 1);
+    this.renderPreviews();
+  }
+
+  renderPreviews() {
+    if (this.hasAttachButtonTarget) {
+      this.attachButtonTarget.textContent = `📎 Attach screenshots (${this.files.length}/${MAX_SCREENSHOTS})`;
+    }
+    if (!this.hasPreviewsTarget) return;
+
+    this.previewsTarget.replaceChildren();
+    this.files.forEach((file, index) => {
+      const wrapper = document.createElement("div");
+      wrapper.style.cssText = "position:relative;width:64px;height:64px;border:1px solid #1f2937;border-radius:6px;overflow:hidden;background:#0a0a0a;";
+
+      const img = document.createElement("img");
+      img.src = file.preview;
+      img.alt = file.filename;
+      img.style.cssText = "width:100%;height:100%;object-fit:cover;";
+      wrapper.appendChild(img);
+
+      const remove = document.createElement("button");
+      remove.type = "button";
+      remove.textContent = "×";
+      remove.setAttribute("aria-label", `Remove ${file.filename}`);
+      remove.style.cssText = "position:absolute;top:2px;right:2px;width:18px;height:18px;line-height:16px;padding:0;background:rgba(0,0,0,0.7);color:#fff;border:none;border-radius:9999px;cursor:pointer;font-size:13px;";
+      remove.addEventListener("click", () => this.removeFile(index));
+      wrapper.appendChild(remove);
+
+      this.previewsTarget.appendChild(wrapper);
+    });
+  }
+
+  readAsDataURL(file) {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => resolve(reader.result);
+      reader.onerror = () => reject(reader.error);
+      reader.readAsDataURL(file);
+    });
+  }
+
+  // --- Submission -----------------------------------------------------------
+
+  async submit() {
+    const description = this.descriptionTarget.value.trim();
+    if (description.length < 5) {
+      this.showError("Please add a little more detail (at least 5 characters).");
+      return;
+    }
+
+    this.submitTarget.disabled = true;
+    this.submitTarget.textContent = "Sending…";
+
+    const payload = {
+      ticket: {
+        description,
+        source: "widget",
+        severity: this.severityValue || null,
+        reporter: this.userValue && Object.keys(this.userValue).length ? this.userValue : null,
+        screenshots: this.files.map((f) => ({
+          filename: f.filename,
+          content_type: f.content_type,
+          data: f.data
+        })),
+        metadata: {
+          ...this.metadataValue,
+          url: window.location.href,
+          user_agent: navigator.userAgent,
+          viewport: `${window.innerWidth}x${window.innerHeight}`,
+          referrer: document.referrer || null,
+          console_errors: this.consoleEntries.slice(),
+          user_path: this.clickPath.slice()
+        }
+      }
+    };
+
+    try {
+      const response = await fetch(this.endpointValue, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.apiKeyValue}`,
+          "Idempotency-Key": crypto.randomUUID(),
+          "X-Dispatch-Widget-Version": WIDGET_VERSION
+        },
+        body: JSON.stringify(payload),
+        mode: "cors"
+      });
+
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Server returned ${response.status}: ${body.slice(0, 200)}`);
+      }
+
+      this.close();
+      this.showToast();
+    } catch (error) {
+      this.showError(error.message || "Something went wrong sending your feedback.");
+    } finally {
+      this.submitTarget.disabled = false;
+      this.submitTarget.textContent = "Send";
+    }
+  }
+
+  showError(message) {
+    this.errorTarget.textContent = message;
+    this.errorTarget.style.display = "block";
+  }
+
+  showToast() {
+    this.toastTarget.hidden = false;
+    setTimeout(() => { this.toastTarget.hidden = true; }, 3000);
+  }
+}
+
+// Auto-register with the host application's Stimulus instance, if present.
+if (window.Stimulus && typeof window.Stimulus.register === "function") {
+  window.Stimulus.register("dispatch-widget", DispatchWidgetController);
+}