nuxt-error-tracker 0.1.3

package/README.md

@@ -0,0 +1,142 @@
+# @ray_of_goodness_/nuxt-error-tracker
+
+Lightweight frontend error tracker for **Nuxt 3 / 4**. Captures unhandled
+errors, failed requests, and a breadcrumb trail of user actions, then ships them
+to your Observer ingest endpoint. Client-only, batched, and built to **never
+break the host app** — if it isn't configured, it does nothing.
+
+## Features
+
+- Captures Vue errors, `window.onerror`, unhandled promise rejections
+- Optional `fetch` instrumentation — auto-reports network failures and 5xx
+- Optional `console.error` capture
+- **Breadcrumbs**: ring buffer of clicks, route changes, fetches and console
+  errors, snapshotted onto each error
+- Batched + debounced sending; force-flush on page hide via `sendBeacon`
+- Per-session dedup so one recurring error can't flood your quota
+- Safe by default: missing keys → plugin is a no-op, never throws
+
+## Install
+
+```bash
+npm i @ray_of_goodness_/nuxt-error-tracker
+# or: bun add @ray_of_goodness_/nuxt-error-tracker
+```
+
+## Setup
+
+Add the module and point it at your ingest endpoint with your project's public
+key:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@ray_of_goodness_/nuxt-error-tracker'],
+  errorTracker: {
+    endpoint: 'https://<your-observer-host>/v1/ingest',
+    publicKey: 'pk_xxxxxxxxxxxxxxxxxxxxxxxx',
+  },
+})
+```
+
+> The public key identifies your project on the ingest side. It's a **public**
+> value — safe to ship in client bundles. Origin allowlisting and rate limiting
+> are enforced server-side.
+
+### No keys? No problem
+
+If `endpoint` or `publicKey` is empty (or `enabled: false`), the plugin is never
+registered and your app runs untouched. This makes it safe to leave the module
+installed while wiring keys per-environment — dev builds without a key simply
+don't track.
+
+## Configuration via environment variables
+
+Every option can be driven from the environment instead of hardcoding it, using
+Nuxt's `runtimeConfig` public-env convention:
+
+```ini
+NUXT_PUBLIC_ERROR_TRACKER_ENDPOINT=https://<your-observer-host>/v1/ingest
+NUXT_PUBLIC_ERROR_TRACKER_PUBLIC_KEY=pk_xxxxxxxxxxxxxxxxxxxxxxxx
+NUXT_PUBLIC_ERROR_TRACKER_APP_VERSION=1.4.2
+```
+
+Wire them in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@ray_of_goodness_/nuxt-error-tracker'],
+  runtimeConfig: {
+    public: {
+      errorTracker: {
+        endpoint: process.env.NUXT_PUBLIC_ERROR_TRACKER_ENDPOINT,
+        publicKey: process.env.NUXT_PUBLIC_ERROR_TRACKER_PUBLIC_KEY,
+        appVersion: process.env.NUXT_PUBLIC_ERROR_TRACKER_APP_VERSION,
+      },
+    },
+  },
+})
+```
+
+## Options
+
+| Option            | Type      | Default     | Description                                                        |
+| ----------------- | --------- | ----------- | ------------------------------------------------------------------ |
+| `endpoint`        | `string`  | `''`        | Ingest URL (`.../v1/ingest`). Required.                            |
+| `publicKey`       | `string`  | `''`        | Your project's public key. Required.                               |
+| `appVersion`      | `string`  | `'unknown'` | Tag every error with a release/version.                            |
+| `enabled`         | `boolean` | `true`      | Master switch. `false` = fully disabled.                           |
+| `captureFetch`    | `boolean` | `true`      | Wrap `fetch` to breadcrumb requests and report failures/5xx.       |
+| `captureConsole`  | `boolean` | `true`      | Patch `console.error` to capture logged-but-not-thrown errors.     |
+| `flushDelay`      | `number`  | `2000`      | Debounce (ms) before a batch is sent.                              |
+| `maxPerSession`   | `number`  | `5`         | Max occurrences of the *same* error captured per session.          |
+| `maxBatch`        | `number`  | `20`        | Max errors per request (server also hard-caps at 20).              |
+| `maxBreadcrumbs`  | `number`  | `30`        | Breadcrumbs kept in the ring buffer / sent per error (max 50).     |
+
+## Runtime helpers
+
+The plugin injects two helpers for manual use:
+
+```ts
+const { $trackError, $addBreadcrumb } = useNuxtApp()
+
+// Report a handled error yourself
+try {
+  await risky()
+} catch (e) {
+  $trackError(e)
+}
+
+// Add your own breadcrumb to the trail
+$addBreadcrumb({
+  type: 'custom',
+  category: 'checkout',
+  message: 'user clicked pay',
+  level: 'info',
+})
+```
+
+## What gets sent
+
+Per error: `message`, `stack`, `source` (`vue` | `window` | `promise` |
+`fetch` | `console`), `url`, `route`, timestamp, and the breadcrumb trail. Once
+per batch: `device` info (user agent, language, screen/viewport, connection),
+`userId` (read from a `user_id` cookie if present), and `appVersion`. Field
+lengths are truncated client-side to match server limits.
+
+### Privacy
+
+Click breadcrumbs record the element (tag / id / class / short text) — **never
+input values**. Nothing is captured until an error occurs; breadcrumbs live only
+in memory and ship attached to an error.
+
+## How it sends
+
+Payloads are encoded as **protobuf** and POSTed as `application/x-protobuf`. On
+page-hide the queue is force-flushed via `navigator.sendBeacon`, falling back to
+`fetch(..., { keepalive: true })`. Binary framing keeps the network panel tidy —
+it is **not** encryption; the schema is public.
+
+## License
+
+MIT

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,24 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    endpoint: string;
+    publicKey: string;
+    appVersion?: string;
+    enabled?: boolean;
+    /** Wrap window.fetch to capture failed requests (network errors + 5xx). Default true. */
+    captureFetch?: boolean;
+    /** Patch console.error to capture logged-but-not-thrown errors. Default true. */
+    captureConsole?: boolean;
+    /** Debounce before a batch is flushed, in ms. Default 2000. */
+    flushDelay?: number;
+    /** Max occurrences of the same error captured per session. Default 5. */
+    maxPerSession?: number;
+    /** Max errors per flushed batch. Default 20 (server also caps at 20). */
+    maxBatch?: number;
+    /** Max breadcrumbs kept in the ring buffer / sent per error. Default 30. */
+    maxBreadcrumbs?: number;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,24 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    endpoint: string;
+    publicKey: string;
+    appVersion?: string;
+    enabled?: boolean;
+    /** Wrap window.fetch to capture failed requests (network errors + 5xx). Default true. */
+    captureFetch?: boolean;
+    /** Patch console.error to capture logged-but-not-thrown errors. Default true. */
+    captureConsole?: boolean;
+    /** Debounce before a batch is flushed, in ms. Default 2000. */
+    flushDelay?: number;
+    /** Max occurrences of the same error captured per session. Default 5. */
+    maxPerSession?: number;
+    /** Max errors per flushed batch. Default 20 (server also caps at 20). */
+    maxBatch?: number;
+    /** Max breadcrumbs kept in the ring buffer / sent per error. Default 30. */
+    maxBreadcrumbs?: number;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@ray_of_goodness_/nuxt-error-tracker",
+  "configKey": "errorTracker",
+  "version": "0.1.3",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "2.0.0"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,55 @@
+import { defineNuxtModule, extendViteConfig, createResolver, addPlugin } from '@nuxt/kit';
+
+function posInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+const module = defineNuxtModule({
+  meta: {
+    name: "@ray_of_goodness_/nuxt-error-tracker",
+    configKey: "errorTracker"
+  },
+  defaults: {
+    endpoint: "",
+    publicKey: "",
+    appVersion: "unknown",
+    enabled: true,
+    captureFetch: true,
+    captureConsole: true,
+    flushDelay: 2e3,
+    maxPerSession: 5,
+    maxBatch: 20,
+    maxBreadcrumbs: 30
+  },
+  setup(options, nuxt) {
+    if (!options.enabled || !options.endpoint || !options.publicKey)
+      return;
+    nuxt.options.runtimeConfig.public.errorTracker = {
+      endpoint: options.endpoint,
+      publicKey: options.publicKey,
+      appVersion: options.appVersion ?? "unknown",
+      captureFetch: options.captureFetch !== false,
+      captureConsole: options.captureConsole !== false,
+      flushDelay: posInt(options.flushDelay, 2e3),
+      maxPerSession: posInt(options.maxPerSession, 5),
+      // Server hard-caps batches at 20 — never emit larger, even if misconfigured.
+      maxBatch: Math.min(posInt(options.maxBatch, 20), 20),
+      // Server DTO caps at 50 breadcrumbs — stay at or below.
+      maxBreadcrumbs: Math.min(posInt(options.maxBreadcrumbs, 30), 50)
+    };
+    extendViteConfig((config) => {
+      config.optimizeDeps ||= {};
+      config.optimizeDeps.include ||= [];
+      if (!config.optimizeDeps.include.includes("protobufjs")) {
+        config.optimizeDeps.include.push("protobufjs");
+      }
+    });
+    const resolver = createResolver(import.meta.url);
+    addPlugin({
+      src: resolver.resolve("./runtime/plugin.client"),
+      mode: "client"
+    });
+  }
+});
+
+export { module as default };

package/dist/runtime/ingest.codec.d.ts

@@ -0,0 +1,27 @@
+export interface Crumb {
+    type?: string;
+    category?: string;
+    message?: string;
+    level?: string;
+    timestamp?: string;
+    data?: Record<string, unknown>;
+}
+export interface FlushError {
+    message: string;
+    stack: string;
+    source: string;
+    url: string;
+    route: string;
+    occurredAt: string;
+    breadcrumbs?: Crumb[];
+}
+export interface FlushBody {
+    meta: {
+        device?: Record<string, unknown>;
+        userId?: string | null;
+        appVersion?: string;
+    };
+    errors: FlushError[];
+}
+/** Encode a flush body to protobuf bytes matching the shared Batch schema. */
+export declare function encodeBatch(body: FlushBody): Uint8Array;

package/dist/runtime/ingest.codec.js

@@ -0,0 +1,70 @@
+import protobuf from "protobufjs";
+const INGEST_PROTO = `
+syntax = "proto3";
+message Breadcrumb {
+  string type = 1;
+  string category = 2;
+  string message = 3;
+  string level = 4;
+  string timestamp = 5;
+  string data = 6;
+}
+message Error {
+  string message = 1;
+  string stack = 2;
+  string source = 3;
+  string url = 4;
+  string route = 5;
+  string userId = 6;
+  string appVersion = 7;
+  string device = 8;
+  string occurredAt = 9;
+  repeated Breadcrumb breadcrumbs = 10;
+}
+message Meta {
+  string device = 1;
+  string userId = 2;
+  string appVersion = 3;
+}
+message Batch {
+  Meta meta = 1;
+  repeated Error errors = 2;
+}
+`;
+const Batch = protobuf.parse(INGEST_PROTO).root.lookupType("Batch");
+function jsonStr(v) {
+  if (v === void 0 || v === null) return "";
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return "";
+  }
+}
+export function encodeBatch(body) {
+  const message = {
+    meta: {
+      device: jsonStr(body.meta.device),
+      userId: body.meta.userId ?? "",
+      appVersion: body.meta.appVersion ?? ""
+    },
+    errors: body.errors.map((e) => ({
+      message: e.message,
+      stack: e.stack,
+      source: e.source,
+      url: e.url,
+      route: e.route,
+      appVersion: "",
+      device: "",
+      occurredAt: e.occurredAt,
+      breadcrumbs: (e.breadcrumbs ?? []).map((c) => ({
+        type: c.type ?? "",
+        category: c.category ?? "",
+        message: c.message ?? "",
+        level: c.level ?? "",
+        timestamp: c.timestamp ?? "",
+        data: jsonStr(c.data)
+      }))
+    }))
+  };
+  return Batch.encode(Batch.fromObject(message)).finish();
+}

package/dist/runtime/plugin.client.d.ts

@@ -0,0 +1,2 @@
+declare const _default: any;
+export default _default;

package/dist/runtime/plugin.client.js

@@ -0,0 +1,204 @@
+import {
+  defineNuxtPlugin,
+  useCookie,
+  useRoute,
+  useRouter,
+  useRuntimeConfig
+} from "#imports";
+import { encodeBatch } from "./ingest.codec.js";
+export default defineNuxtPlugin((nuxtApp) => {
+  const config = useRuntimeConfig().public.errorTracker;
+  if (!config || !config.endpoint || !config.publicKey) return;
+  const route = useRoute();
+  const FLUSH_DELAY = config.flushDelay ?? 2e3;
+  const MAX_PER_SESSION = config.maxPerSession ?? 5;
+  const MAX_BATCH = config.maxBatch ?? 20;
+  const MAX_CRUMBS = config.maxBreadcrumbs ?? 30;
+  const queue = [];
+  const sessionCounts = /* @__PURE__ */ new Map();
+  let flushTimer = null;
+  const crumbs = [];
+  function addCrumb(c) {
+    crumbs.push({ ...c, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+    if (crumbs.length > MAX_CRUMBS) crumbs.shift();
+  }
+  function deviceInfo() {
+    return {
+      userAgent: navigator.userAgent,
+      language: navigator.language,
+      platform: navigator.platform,
+      screen: `${window.screen.width}x${window.screen.height}`,
+      viewport: `${window.innerWidth}x${window.innerHeight}`,
+      online: navigator.onLine,
+      memory: navigator.deviceMemory ?? null,
+      connection: navigator.connection?.effectiveType ?? null
+    };
+  }
+  function resolveUserId() {
+    return useCookie("user_id").value ?? null;
+  }
+  function sessionKey(message, stack) {
+    return `${message.slice(0, 120)}::${(stack.split("\n")[1] ?? "").trim()}`;
+  }
+  function flush(useBeacon = false) {
+    if (!queue.length) return;
+    const batch = queue.splice(0, MAX_BATCH);
+    const body = {
+      meta: {
+        device: deviceInfo(),
+        userId: resolveUserId(),
+        appVersion: config.appVersion
+      },
+      errors: batch
+    };
+    const bytes = encodeBatch(body);
+    if (useBeacon && navigator.sendBeacon) {
+      const url = `${config.endpoint}?key=${encodeURIComponent(config.publicKey)}`;
+      const sent = navigator.sendBeacon(
+        url,
+        new Blob([bytes], { type: "application/x-protobuf" })
+      );
+      if (sent) return;
+    }
+    fetch(config.endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-protobuf",
+        "X-Public-Key": config.publicKey
+      },
+      body: bytes,
+      keepalive: true
+    }).catch(() => {
+      queue.unshift(...batch);
+    });
+  }
+  function scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      flush();
+    }, FLUSH_DELAY);
+  }
+  function capture(err, source) {
+    try {
+      const error = err instanceof Error ? err : new Error(String(err));
+      if (error.message === "Script error.") return;
+      const key = sessionKey(error.message, error.stack ?? "");
+      const count = sessionCounts.get(key) ?? 0;
+      if (count >= MAX_PER_SESSION) return;
+      sessionCounts.set(key, count + 1);
+      queue.push({
+        message: error.message.slice(0, 1e3),
+        stack: (error.stack ?? "").slice(0, 8e3),
+        source,
+        url: window.location.href.slice(0, 2e3),
+        route: route.fullPath.slice(0, 500),
+        occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+        // Snapshot the trail leading up to this error (copy, not reference).
+        breadcrumbs: crumbs.slice(-MAX_CRUMBS)
+      });
+      scheduleFlush();
+    } catch {
+    }
+  }
+  nuxtApp.hook("vue:error", (err) => capture(err, "vue"));
+  window.addEventListener(
+    "error",
+    (event) => capture(event.error ?? event.message, "window")
+  );
+  window.addEventListener(
+    "unhandledrejection",
+    (event) => capture(event.reason, "promise")
+  );
+  document.addEventListener(
+    "click",
+    (event) => {
+      const el = event.target;
+      if (!el || !el.tagName) return;
+      const tag = el.tagName.toLowerCase();
+      const id = el.id ? `#${el.id}` : "";
+      const cls = typeof el.className === "string" && el.className ? `.${el.className.trim().split(/\s+/).slice(0, 2).join(".")}` : "";
+      const text = (el.textContent ?? "").trim().slice(0, 40);
+      addCrumb({
+        type: "click",
+        category: "ui.click",
+        message: `${tag}${id}${cls}${text ? ` "${text}"` : ""}`
+      });
+    },
+    { capture: true, passive: true }
+  );
+  useRouter().afterEach((to, from) => {
+    addCrumb({
+      type: "navigation",
+      category: "navigation",
+      message: `${from.fullPath} \u2192 ${to.fullPath}`
+    });
+  });
+  if (config.captureFetch && typeof window.fetch === "function") {
+    const originalFetch = window.fetch.bind(window);
+    window.fetch = async (input, init) => {
+      const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+      const reqUrl = input instanceof Request ? input.url : String(input);
+      const isOwn = reqUrl.startsWith(config.endpoint);
+      try {
+        const res = await originalFetch(input, init);
+        if (!isOwn) {
+          addCrumb({
+            type: "fetch",
+            category: "http",
+            level: res.status >= 400 ? "error" : "info",
+            message: `${method} ${reqUrl} \u2192 ${res.status}`
+          });
+          if (res.status >= 500) {
+            capture(
+              new Error(`HTTP ${res.status} ${method} ${reqUrl}`),
+              "fetch"
+            );
+          }
+        }
+        return res;
+      } catch (err) {
+        if (!isOwn) {
+          const reason = err instanceof Error ? err.message : String(err);
+          addCrumb({
+            type: "fetch",
+            category: "http",
+            level: "error",
+            message: `${method} ${reqUrl} \u2192 failed: ${reason}`
+          });
+          capture(
+            new Error(`Fetch failed ${method} ${reqUrl}: ${reason}`),
+            "fetch"
+          );
+        }
+        throw err;
+      }
+    };
+  }
+  if (config.captureConsole) {
+    const originalError = console.error.bind(console);
+    console.error = (...args) => {
+      const errArg = args.find((a) => a instanceof Error);
+      const message = errArg?.message ?? args.map((a) => typeof a === "string" ? a : String(a)).join(" ").slice(0, 1e3);
+      if (message) {
+        addCrumb({
+          type: "console",
+          category: "console",
+          level: "error",
+          message
+        });
+        capture(errArg ?? new Error(message), "console");
+      }
+      originalError(...args);
+    };
+  }
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush(true);
+  });
+  return {
+    provide: {
+      trackError: (err) => capture(err, "window"),
+      addBreadcrumb: (c) => addCrumb(c)
+    }
+  };
+});

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "nuxt-error-tracker",
+  "version": "0.1.3",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "prepublishOnly": "nuxt-module-build build"
+  },
+  "dependencies": {
+    "protobufjs": "^8.6.6"
+  },
+  "peerDependencies": {
+    "@nuxt/kit": "^3.14.0 || ^4.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/kit": "^3.14.0",
+    "@nuxt/module-builder": "^0.8.0",
+    "nuxt": "^3.14.0"
+  }
+}