nuxt-error-tracker 0.1.17 → 0.1.19

package/LICENSE

@@ -0,0 +1,91 @@
+# PolyForm Shield License 1.0.0
+
+<https://polyformproject.org/licenses/shield/1.0.0>
+
+Required Notice: Copyright ray_of_goodness_
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncompete
+
+Any purpose is a permitted purpose, except for providing any product that competes with the software or any product the licensor or any of its affiliates provides using the software.
+
+## Competition
+
+Goods and services compete even when they provide functionality through different kinds of interfaces or for different technical platforms.  Applications can compete with services, libraries with plugins, frameworks with development tools, and so on, even if they're written in different programming languages or for different computer architectures.  Goods and services compete even when provided free of charge.  If you market a product as a practical substitute for the software or another product, it definitely competes.
+
+## New Products
+
+If you are using the software to provide a product that does not compete, but the licensor or any of its affiliates brings your product into competition by providing a new version of the software or another product using the software, you may continue using versions of the software available under these terms beforehand to provide your competing product, but not any later versions.
+
+## Discontinued Products
+
+You may begin using the software to compete with a product or service that the licensor or any of its affiliates has stopped providing, unless the licensor includes a plain-text line beginning with `Licensor Line of Business:` with the software that mentions that line of business.  For example:
+
+> Licensor Line of Business: YoyodyneCMS Content Management System (http://example.com/cms)
+
+## Sales of Business
+
+If the licensor or any of its affiliates sells a line of business developing the software or using the software to provide a product, the buyer can also enforce [Noncompete](#noncompete) for that product.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+A **product** can be a good or service, or a combination of them.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all its affiliates.
+
+**Affiliates** means the other organizations than an organization has control over, is under the control of, or is under common control with.
+
+**Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -1,20 +1,67 @@
 # 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
+**English** · [Українська](./README.uk.md)
 
-- 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
+Lightweight frontend error tracker for **Nuxt 3 / 4**. It captures unhandled
+errors, failed requests, and a breadcrumb trail of user actions, then ships them
+to **your own** Observer ingest endpoint. Client-only, batched, and built to
+**never break the host app** — if it isn't configured, it does nothing.
+
+You bring the URL and a public key; the package does the capturing. Everything
+you send lands under your project in your Observer dashboard, where you view,
+search and manage the logs yourself.
+
+---
+
+## Table of contents
+
+- [How it works (the moving parts)](#how-it-works-the-moving-parts)
+- [Install](#install)
+- [Getting your endpoint and key](#getting-your-endpoint-and-key)
+- [Setup](#setup)
+- [Configuration via environment variables](#configuration-via-environment-variables)
+- [Options](#options)
+- [Runtime helpers](#runtime-helpers)
+- [What gets sent to the API](#what-gets-sent-to-the-api)
+- [Wire format & data types](#wire-format--data-types)
+- [Viewing and controlling your logs](#viewing-and-controlling-your-logs)
+- [Privacy](#privacy)
+- [License](#license)
+
+---
+
+## How it works (the moving parts)
+
+There are three pieces. This package is only the first one.
+
+| Piece | What it is | Responsibility |
+| --- | --- | --- |
+| **This package** (`nuxt-error-tracker`) | A Nuxt module you install in your app | Hooks into the browser, captures errors + breadcrumbs, batches them, and POSTs to your endpoint. Runs **client-side only**. |
+| **Your ingest endpoint** (`.../v1/ingest`) | The Observer API you host (or are given access to) | Authenticates the request by public key + origin, validates and rate-limits it, deduplicates errors by fingerprint, and stores them. |
+| **Your dashboard** | The Observer console UI | Where **you** browse, search, and manage the logs — stack traces, occurrences, breadcrumb trails, retention. |
+
+The package never decides *where* the data goes — **you do**, by pointing
+`endpoint` at your host. It ships no default URL. Swap the host and your logs
+follow. This is what makes it "bring your own backend": the same package works
+against localhost during development and your production Observer instance in
+release, just by changing the endpoint.
+
+Inside the package itself:
+
+- **`module.ts`** — the Nuxt module. Reads your options, and **only registers
+  the capture plugin if `enabled` + `endpoint` + `publicKey` are all present**.
+  Missing any of them → the plugin is never added and your app runs untouched.
+  It also normalizes options (clamps `maxBatch ≤ 20`, `maxBreadcrumbs ≤ 50` to
+  match server limits) and injects TypeScript types for the helpers.
+- **`plugin.client.ts`** — the actual capture engine (browser only). Listens for
+  errors, wraps `fetch`, patches `console.error`, records breadcrumbs, and
+  manages the send queue.
+- **`plugin.server.ts`** — a tiny SSR stub. Provides no-op `$trackError` /
+  `$addBreadcrumb` so calling them during server-side rendering never throws.
+- **`ingest.codec.ts`** — a hand-rolled protobuf encoder (no dependencies) that
+  turns a batch into the binary wire format the API expects.
+
+---
 
 ## Install
 
@@ -23,31 +70,47 @@ npm i nuxt-error-tracker
 # or: bun add nuxt-error-tracker
 ```
 
-## Getting your keys
+---
 
-The module needs two values — an **ingest endpoint** and a **public key**. Both
-come from your Observer dashboard. Everything after step 4 is what you paste into
-the app; from then on your errors show up in the same dashboard.
+## Getting your endpoint and key
+
+The module needs exactly two things to start reporting: an **ingest endpoint**
+(your URL) and a **public key** (which project the errors belong to). Both come
+from your Observer dashboard.
 
 1. Open the dashboard at `https://<your-observer-host>/dashboard`.
-2. **Create account** — enter an email and a password (min 8 chars), submit. You
-   stay signed in via a secure cookie.
+2. **Create an account** — enter an email and a password (min 8 chars), submit.
+   You stay signed in via a secure httpOnly cookie.
 3. Click **New project**, give it a name (e.g. `my-app`), and optionally list the
-   origins your site runs on (comma-separated, e.g. `https://my-app.com,
-   http://localhost:3000`). Empty = accept any origin. This is the server-side
-   allowlist — requests from other origins are rejected.
-4. The project now shows a **public key** (`pk_…`) and a ready-made
-   `nuxt.config` snippet. Use **Copy key** / **Copy config**.
+   origins your site runs on (comma-separated, e.g.
+   `https://my-app.com, http://localhost:3000`). Empty = accept any origin. This
+   is the **server-side allowlist** — requests from other origins are rejected.
+4. The project now shows a **public key** (`pk_…`) and a ready-made `nuxt.config`
+   snippet. Use **Copy key** / **Copy config**.
 5. The **endpoint** is your host + `/v1/ingest`, i.e.
    `https://<your-observer-host>/v1/ingest`.
 
-Then configure the package ([Setup](#setup)) and deploy. Captured errors appear
-under that project in the dashboard — open **Logs** on the project to browse
-them, with stack traces, recent occurrences and the breadcrumb trail.
+### What the two values actually do
+
+- **`endpoint`** — *where* to send. This is your URL. Point it at whatever host
+  runs the Observer API. There is no hosted default; you are always sending to
+  your own backend.
+- **`publicKey`** — *whose project* the errors are. On every request the API
+  looks up the project by this key (`X-Public-Key` header, or `?key=` query for
+  the beacon path), then enforces that project's origin allowlist and rate
+  limit. It is a **public** value — safe to ship in client bundles. It grants
+  *write-only* ingest for one project; it does **not** let anyone read your logs.
+  Reading requires your dashboard login.
+
+> **Origins matter.** If you set an allowlist, it must include **every** origin
+> your app is served from — production domains **and** `http://localhost:3000`
+> for local dev — or the browser's requests get a `401`. Leave it empty while
+> experimenting, tighten it for production.
 
-> Origins matter: if you set an allowlist, it must include every origin your app
-> is served from (prod domains **and** `http://localhost:3000` for local dev),
-> or the browser's requests get a 401.
+Once configured (below) and deployed, captured errors appear under that project
+in the dashboard. Open **Logs** on the project to browse them.
+
+---
 
 ## Setup
 
@@ -65,16 +128,16 @@ export default defineNuxtConfig({
 })
 ```
 
-> 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.
+That's the minimum. Everything else has sensible defaults.
 
 ### 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.
+don't track. There is no crash, no console noise, no network call.
+
+---
 
 ## Configuration via environment variables
 
@@ -104,21 +167,32 @@ export default defineNuxtConfig({
 })
 ```
 
+This is the recommended way to point the same build at a **different endpoint**
+per environment (staging vs. production) without touching code.
+
+---
+
 ## 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.     |
-| `captureInputs`   | `boolean` | `false`     | Record form input values as breadcrumbs (on change). Sensitive fields masked. Opt-in — captures user-entered data. |
-| `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).     |
+| Option                | Type      | Default     | Description                                                        |
+| --------------------- | --------- | ----------- | ------------------------------------------------------------------ |
+| `endpoint`            | `string`  | `''`        | Ingest URL (`.../v1/ingest`). **Required** — your host.            |
+| `publicKey`           | `string`  | `''`        | Your project's public key (`pk_…`). **Required**.                  |
+| `appVersion`          | `string`  | `'unknown'` | Tags every batch with a release/version so you can filter by it.   |
+| `enabled`             | `boolean` | `true`      | Master switch. `false` = fully disabled, plugin not registered.    |
+| `captureFetch`        | `boolean` | `true`      | Wrap `fetch` to breadcrumb requests and report failures / 5xx.     |
+| `captureFetchDetails` | `boolean` | `true`      | Attach full request/response detail (method, status, timing, headers, request payload, response body) to each fetch breadcrumb. Sensitive headers redacted, bodies truncated to 2 KB. Set `false` to keep fetch crumbs message-only (avoids capturing payloads / PII). |
+| `captureConsole`      | `boolean` | `true`      | Patch `console.error` to capture logged-but-not-thrown errors.     |
+| `captureInputs`       | `boolean` | `false`     | Record form input values as breadcrumbs (on change/blur). Sensitive fields masked. **Opt-in** — captures user-entered data. |
+| `flushDelay`          | `number`  | `2000`      | Debounce (ms) before a queued batch is sent.                       |
+| `minFlushInterval`    | `number`  | `0`         | Floor (ms) between consecutive flushes — throttles request rate during an error storm. `0` = off. |
+| `sampleRate`          | `number`  | `1`         | Fraction (0..1) of captured errors actually sent; the rest are dropped at capture. `0.3` ≈ keep 30%. Thins volume before the server rate limit. |
+| `maxPerMinute`        | `number`  | `0`         | Client-side cap on errors queued per rolling minute (fixed window); excess dropped. Mirrors the server per-project rate limit. `0` = unlimited. |
+| `maxPerSession`       | `number`  | `5`         | Max occurrences of the *same* error captured per session.          |
+| `maxBatch`            | `number`  | `20`        | Max errors per request (clamped to server hard cap of 20).         |
+| `maxBreadcrumbs`      | `number`  | `30`        | Breadcrumbs kept in the ring buffer / sent per error (clamped to 50). |
+
+---
 
 ## Runtime helpers
 
@@ -153,19 +227,141 @@ augmentation for `NuxtApp` and Vue's `ComponentCustomProperties`, so both
 `useNuxtApp()` and template usage resolve them as functions (no `unknown` /
 TS18046). No manual `.d.ts` needed.
 
-## What gets sent
+---
+
+## What gets sent to the API
+
+Nothing is sent until an error occurs. The package keeps an in-memory breadcrumb
+ring buffer as the user interacts; when an error is captured, it snapshots that
+trail, queues the error, and (after a debounce) POSTs a **batch**.
+
+A batch has two parts: **`meta`** (sent once per batch, applies to all errors in
+it) and **`errors`** (the array of captured errors).
+
+### `meta` (once per batch)
+
+| Field        | Type     | Source | Notes |
+| ------------ | -------- | ------ | ----- |
+| `device`     | `object` | `navigator` / `window` | `userAgent`, `language`, `platform`, `screen` (`WxH`), `viewport` (`WxH`), `online` (bool), `memory` (`deviceMemory`, GB or `null`), `connection` (`effectiveType` or `null`). Server caps the JSON at 2 KB. |
+| `userId`     | `string` \| `null` | `user_id` cookie | Read from a cookie named `user_id` if present, else `null`. The package never invents an id. Max 100 chars. |
+| `appVersion` | `string` | your `appVersion` option | Defaults to `'unknown'`. Max 50 chars. |
+
+### `errors[]` (per captured error)
+
+| Field         | Type      | Description | Limit |
+| ------------- | --------- | ----------- | ----- |
+| `message`     | `string`  | Error message. | ≤ 1000 chars |
+| `stack`       | `string`  | Stack trace. | ≤ 8000 chars |
+| `source`      | `string`  | Where it came from: `vue`, `window`, `promise`, `fetch`, or `console`. | ≤ 20 chars |
+| `level`       | `string`  | Severity: `fatal` \| `error` \| `warning` \| `info` \| `debug`. | one of |
+| `url`         | `string`  | `window.location.href` at capture time. | ≤ 2000 chars |
+| `route`       | `string`  | Nuxt route `fullPath`. | ≤ 500 chars |
+| `occurredAt`  | `string`  | ISO-8601 timestamp. | ISO-8601 |
+| `breadcrumbs` | `Breadcrumb[]` | The trail leading up to the error (see below). | ≤ 50 items |
+
+Each **`Breadcrumb`**:
+
+| Field       | Type     | Description | Limit |
+| ----------- | -------- | ----------- | ----- |
+| `type`      | `string` | `click`, `input`, `navigation`, `fetch`, `console`, or your custom type. | ≤ 30 chars |
+| `category`  | `string` | e.g. `ui.click`, `ui.input`, `navigation`, `http`, `console`. | ≤ 60 chars |
+| `message`   | `string` | Human-readable line, e.g. `POST /api/pay → 500`. | ≤ 500 chars |
+| `level`     | `string` | `info` \| `error` \| … | ≤ 20 chars |
+| `timestamp` | `string` | ISO-8601. | ISO-8601 |
+| `data`      | `object` | Optional structured payload (fetch details: method, status, timing, headers, request/response bodies). | JSON |
+
+**Batch caps:** at most **20 errors per request**; the client also re-queues
+failed batches (bounded to 200 in memory) and dedups the *same* error to
+`maxPerSession` (5) occurrences per session, so one recurring error can't flood
+your quota.
+
+---
+
+## Wire format & data types
+
+Payloads are encoded as **protobuf** (proto3) and POSTed as
+`application/x-protobuf`. The encoder is hand-rolled and has **zero
+dependencies** — no `protobufjs`, so consumers need no Vite `optimizeDeps` or
+CJS-interop config.
+
+The schema (field numbers are load-bearing — they must match the API decoder):
+
+```proto
+message Breadcrumb {
+  string type      = 1;
+  string category  = 2;
+  string message   = 3;
+  string level     = 4;
+  string timestamp = 5;
+  string data      = 6;  // JSON-stringified object
+}
+
+message Error {
+  string message           = 1;
+  string stack             = 2;
+  string source            = 3;
+  string url               = 4;
+  string route             = 5;
+  string userId            = 6;  // per-error override (unused by this client)
+  string appVersion        = 7;  // per-error override (unused by this client)
+  string device            = 8;  // per-error override (unused by this client)
+  string occurredAt        = 9;
+  repeated Breadcrumb breadcrumbs = 10;
+  string level             = 11;
+}
+
+message Meta  { string device = 1; string userId = 2; string appVersion = 3; }
+message Batch { Meta meta = 1; repeated Error errors = 2; }
+```
+
+`device` and breadcrumb `data` are objects, so they travel as
+**JSON-stringified strings** inside the protobuf. Empty strings are omitted
+(proto3 default). The binary framing just keeps the network panel tidy — it is
+**not** encryption; the schema is public, so anyone with it can decode a payload.
+
+### How it's transmitted
+
+- Normal path: `fetch(endpoint, { method: 'POST', headers: { 'Content-Type':
+  'application/x-protobuf', 'X-Public-Key': <key> }, body: <bytes>, keepalive:
+  true })`.
+- Page-hide path: the queue is force-flushed via `navigator.sendBeacon(endpoint
+  + '?key=<key>', Blob)` — because a beacon can't set headers, the key rides in
+  the `?key=` query param. Falls back to `fetch(..., { keepalive: true })` if
+  `sendBeacon` is unavailable or refuses.
+
+The API also accepts plain JSON at the same endpoint (same validation), which is
+handy for scripted test posts, but the SDK always sends protobuf.
+
+---
+
+## Viewing and controlling your logs
+
+The point of bringing your own endpoint: after the package sends, **you** own the
+data and control it entirely from your dashboard — no third-party console.
+
+- **Browse** — open **Logs** on the project to see error groups, each with its
+  message, count, first/last seen, affected routes, and per-occurrence stack
+  trace + breadcrumb trail (including captured fetch payloads/responses when
+  `captureFetchDetails` is on).
+- **Deduplication** — the API groups occurrences by a **fingerprint** (a hash of
+  the normalized message + top stack frames), so a recurring error is one row
+  with a count, not thousands of duplicates.
+- **Rate limit & origins** — each project has its own per-minute rate limit and
+  origin allowlist. Tighten origins to reject stray traffic; the key alone is not
+  enough to get data in from an unlisted origin.
+- **Retention** — occurrences are purged after a retention window (7 days by
+  default on the server), so storage stays bounded without any action from you.
+
+Because the key is write-only and reading is gated by your login, shipping the
+key in your client bundle exposes no stored data.
 
-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
+## 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.
+Click breadcrumbs record the element (tag / id / class / short text / `data-*`
+attributes) — **never input values**. Nothing is captured until an error occurs;
+breadcrumbs live only in memory and ship attached to an error.
 
 Input values are **only** captured when you opt in with `captureInputs: true`.
 Even then, sensitive fields are masked (stored as `[masked, N chars]`, never in
@@ -173,13 +369,16 @@ the clear): any `type="password"`, plus fields whose `name` / `id` /
 `autocomplete` match `pass`, `secret`, `token`, `otp`, `cvv`, `card`, `iban`,
 `ssn`, `pin`, `auth`, etc. Non-sensitive values are truncated to 100 chars.
 
-## How it sends
+Fetch detail capture (`captureFetchDetails`, on by default) redacts sensitive
+request/response headers (`authorization`, `cookie`, `x-api-key`, CSRF tokens, …)
+and truncates bodies to 2 KB. Set it to `false` if you don't want request
+payloads or response bodies leaving the browser at all.
 
-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
+[PolyForm Shield 1.0.0](./LICENSE) — source-available. Free to install and use
+for any purpose **except** building a product that competes with this software or
+with what the licensor offers using it. You may not fork it into a rival. Full
+terms in [`LICENSE`](./LICENSE); copyright remains with the author.

package/README.uk.md

@@ -0,0 +1,388 @@
+# nuxt-error-tracker
+
+[English](./README.md) · **Українська**
+
+Легкий трекер frontend-помилок для **Nuxt 3 / 4**. Перехоплює неопрацьовані
+помилки, невдалі запити та ланцюжок дій користувача (breadcrumbs), після чого
+відправляє їх на **ваш власний** Observer ingest-endpoint. Працює лише на
+клієнті, батчами, і збудований так, щоб **ніколи не ламати застосунок-хост** —
+якщо його не налаштовано, він не робить нічого.
+
+Ви даєте URL і публічний ключ; пакет робить перехоплення. Усе відправлене
+потрапляє під ваш проєкт у вашому Observer-дашборді, де ви самі переглядаєте,
+шукаєте та керуєте логами.
+
+---
+
+## Зміст
+
+- [Як це працює (складові)](#як-це-працює-складові)
+- [Встановлення](#встановлення)
+- [Отримати endpoint і ключ](#отримати-endpoint-і-ключ)
+- [Налаштування](#налаштування)
+- [Конфігурація через змінні середовища](#конфігурація-через-змінні-середовища)
+- [Опції](#опції)
+- [Runtime-хелпери](#runtime-хелпери)
+- [Що відправляється на API](#що-відправляється-на-api)
+- [Формат передачі та типи даних](#формат-передачі-та-типи-даних)
+- [Перегляд і контроль ваших логів](#перегляд-і-контроль-ваших-логів)
+- [Приватність](#приватність)
+- [Ліцензія](#ліцензія)
+
+---
+
+## Як це працює (складові)
+
+Складових три. Цей пакет — лише перша.
+
+| Складова | Що це | За що відповідає |
+| --- | --- | --- |
+| **Цей пакет** (`nuxt-error-tracker`) | Nuxt-модуль, який ви ставите у застосунок | Підключається до браузера, перехоплює помилки + breadcrumbs, батчить їх і POSTить на ваш endpoint. Працює **лише на клієнті**. |
+| **Ваш ingest-endpoint** (`.../v1/ingest`) | Observer API, який ви хостите (або маєте доступ) | Автентифікує запит за публічним ключем + origin, валідує та rate-лімітує, дедуплікує помилки за fingerprint і зберігає. |
+| **Ваш дашборд** | Консоль Observer | Де **ви** переглядаєте, шукаєте та керуєте логами — стек-трейси, occurrences, breadcrumb-ланцюжки, retention. |
+
+Пакет ніколи не вирішує, *куди* йдуть дані — **вирішуєте ви**, вказавши
+`endpoint` на свій хост. Дефолтного URL немає. Змініть хост — логи підуть за
+ним. Це і є «bring your own backend»: той самий пакет працює проти localhost під
+час розробки та проти вашого прод-Observer у релізі, лише зміною endpoint.
+
+Усередині самого пакета:
+
+- **`module.ts`** — Nuxt-модуль. Читає ваші опції та **реєструє плагін
+  перехоплення лише коли `enabled` + `endpoint` + `publicKey` присутні всі**.
+  Немає будь-чого → плагін не додається, застосунок працює недоторканим. Також
+  нормалізує опції (обрізає `maxBatch ≤ 20`, `maxBreadcrumbs ≤ 50` під серверні
+  ліміти) і додає TypeScript-типи для хелперів.
+- **`plugin.client.ts`** — власне рушій перехоплення (лише браузер). Слухає
+  помилки, обгортає `fetch`, патчить `console.error`, пише breadcrumbs і керує
+  чергою відправки.
+- **`plugin.server.ts`** — маленька SSR-заглушка. Дає no-op `$trackError` /
+  `$addBreadcrumb`, щоб виклик під час серверного рендеру ніколи не кидав
+  помилку.
+- **`ingest.codec.ts`** — саморобний protobuf-енкодер (без залежностей), що
+  перетворює батч на бінарний формат, який очікує API.
+
+---
+
+## Встановлення
+
+```bash
+npm i nuxt-error-tracker
+# або: bun add nuxt-error-tracker
+```
+
+---
+
+## Отримати endpoint і ключ
+
+Модулю потрібні рівно дві речі, щоб почати звітувати: **ingest-endpoint** (ваш
+URL) і **публічний ключ** (якому проєкту належать помилки). Обидва беруться з
+вашого Observer-дашборда.
+
+1. Відкрийте дашборд за адресою `https://<ваш-observer-хост>/dashboard`.
+2. **Створіть акаунт** — введіть email і пароль (мін. 8 символів), надішліть.
+   Ви лишаєтесь залогіненим через захищений httpOnly-cookie.
+3. Натисніть **New project**, дайте назву (напр. `my-app`) і за бажанням
+   перелічіть origins, на яких працює ваш сайт (через кому, напр.
+   `https://my-app.com, http://localhost:3000`). Порожньо = приймати будь-який
+   origin. Це **серверний allowlist** — запити з інших origins відхиляються.
+4. Проєкт тепер показує **публічний ключ** (`pk_…`) і готовий сніпет
+   `nuxt.config`. Використайте **Copy key** / **Copy config**.
+5. **Endpoint** — це ваш хост + `/v1/ingest`, тобто
+   `https://<ваш-observer-хост>/v1/ingest`.
+
+### Що насправді роблять ці два значення
+
+- **`endpoint`** — *куди* відправляти. Це ваш URL. Вказуйте на будь-який хост, де
+  крутиться Observer API. Хостованого дефолту немає; ви завжди шлете на свій
+  бекенд.
+- **`publicKey`** — *чий проєкт* помилки. На кожному запиті API шукає проєкт за
+  цим ключем (заголовок `X-Public-Key` або query `?key=` для beacon-шляху), потім
+  застосовує allowlist origins і rate-ліміт цього проєкту. Це **публічне**
+  значення — безпечно класти у клієнтські бандли. Воно дає *лише запис* (ingest)
+  в один проєкт; воно **не** дає нікому читати ваші логи. Читання вимагає логіну в
+  дашборд.
+
+> **Origins важливі.** Якщо ви задали allowlist, він мусить містити **кожен**
+> origin, з якого віддається застосунок — прод-домени **та** `http://localhost:3000`
+> для локальної розробки — інакше запити браузера отримають `401`. Лишіть порожнім
+> під час експериментів, звузьте для продакшену.
+
+Після налаштування (нижче) і деплою перехоплені помилки з'являються під цим
+проєктом у дашборді. Відкрийте **Logs** на проєкті, щоб їх переглянути.
+
+---
+
+## Налаштування
+
+Додайте модуль і вкажіть йому ingest-endpoint з публічним ключем вашого проєкту:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-error-tracker'],
+  errorTracker: {
+    endpoint: 'https://<ваш-observer-хост>/v1/ingest',
+    publicKey: 'pk_xxxxxxxxxxxxxxxxxxxxxxxx',
+  },
+})
+```
+
+Це мінімум. Усе решта має розумні дефолти.
+
+### Немає ключів? Не проблема
+
+Якщо `endpoint` чи `publicKey` порожні (або `enabled: false`), плагін не
+реєструється, і застосунок працює недоторканим. Тому модуль можна лишати
+встановленим, підключаючи ключі по-середовищах — dev-збірки без ключа просто не
+трекають. Ні падіння, ні шуму в консолі, ні мережевого виклику.
+
+---
+
+## Конфігурація через змінні середовища
+
+Кожну опцію можна задати зі змінних середовища замість хардкоду, за конвенцією
+публічних env у Nuxt `runtimeConfig`:
+
+```ini
+NUXT_PUBLIC_ERROR_TRACKER_ENDPOINT=https://<ваш-observer-хост>/v1/ingest
+NUXT_PUBLIC_ERROR_TRACKER_PUBLIC_KEY=pk_xxxxxxxxxxxxxxxxxxxxxxxx
+NUXT_PUBLIC_ERROR_TRACKER_APP_VERSION=1.4.2
+```
+
+Підключіть їх у `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['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,
+      },
+    },
+  },
+})
+```
+
+Це рекомендований спосіб націлити ту саму збірку на **різний endpoint** за
+середовищем (staging vs. production) без правки коду.
+
+---
+
+## Опції
+
+| Опція                 | Тип       | Дефолт      | Опис                                                               |
+| --------------------- | --------- | ----------- | ------------------------------------------------------------------ |
+| `endpoint`            | `string`  | `''`        | Ingest URL (`.../v1/ingest`). **Обовʼязково** — ваш хост.          |
+| `publicKey`           | `string`  | `''`        | Публічний ключ вашого проєкту (`pk_…`). **Обовʼязково**.           |
+| `appVersion`          | `string`  | `'unknown'` | Тегує кожен батч релізом/версією для фільтрації.                   |
+| `enabled`             | `boolean` | `true`      | Головний вимикач. `false` = повністю вимкнено, плагін не реєструється. |
+| `captureFetch`        | `boolean` | `true`      | Обгортає `fetch`, щоб breadcrumbʼити запити і звітувати про збої / 5xx. |
+| `captureFetchDetails` | `boolean` | `true`      | Додає повну деталь запиту/відповіді (метод, статус, тайминг, заголовки, тіло запиту, тіло відповіді) до кожного fetch-breadcrumb. Чутливі заголовки редагуються, тіла обрізаються до 2 КБ. `false` — лишити fetch-крихти лише-повідомленням (не захоплювати payload / PII). |
+| `captureConsole`      | `boolean` | `true`      | Патчить `console.error`, щоб ловити залоговані-але-не-кинуті помилки. |
+| `captureInputs`       | `boolean` | `false`     | Записує значення полів форм як breadcrumbs (на change/blur). Чутливі поля маскуються. **Opt-in** — захоплює введені користувачем дані. |
+| `flushDelay`          | `number`  | `2000`      | Debounce (мс) перед відправкою черги-батча.                        |
+| `minFlushInterval`    | `number`  | `0`         | Мін. пауза (мс) між флашами — throttle частоти запитів під час шторму помилок. `0` = вимкнено. |
+| `sampleRate`          | `number`  | `1`         | Частка (0..1) захоплених помилок, що реально шлються; решта дропається при capture. `0.3` ≈ 30%. Ріже обʼєм до серверного rate limit. |
+| `maxPerMinute`        | `number`  | `0`         | Клієнтський ліміт помилок у чергу за rolling-хвилину (fixed window); понад — дроп. Дзеркалить серверний per-project rate limit. `0` = без ліміту. |
+| `maxPerSession`       | `number`  | `5`         | Макс. кількість occurrences *тієї самої* помилки за сесію.          |
+| `maxBatch`            | `number`  | `20`        | Макс. помилок на запит (обрізається серверним лімітом 20).         |
+| `maxBreadcrumbs`      | `number`  | `30`        | Breadcrumbs у ring buffer / на помилку (обрізається до 50).        |
+
+---
+
+## Runtime-хелпери
+
+Плагін інʼєктить два хелпери для ручного використання:
+
+```ts
+const { $trackError, $addBreadcrumb } = useNuxtApp()
+
+// Звітувати про опрацьовану помилку самому — опційний рівень серйозності
+// ('fatal' | 'error' | 'warning' | 'info' | 'debug', дефолт 'error')
+try {
+  await mayFail()
+} catch (e) {
+  $trackError(e, 'warning')
+}
+
+// Додати власний breadcrumb у ланцюжок
+$addBreadcrumb({
+  type: 'custom',
+  category: 'checkout',
+  message: 'user clicked pay',
+  level: 'info',
+})
+```
+
+Обидва хелпери завжди викликаються. Реальне перехоплення — **лише на клієнті**; на
+сервері (SSR — напр. верхньорівневий `<script setup>`) це безпечні no-opʼи, тож
+виклик ніколи не кидає помилку.
+
+`$trackError` і `$addBreadcrumb` **повністю типізовані** — модуль постачає
+augmentation для `NuxtApp` і Vue `ComponentCustomProperties`, тож і
+`useNuxtApp()`, і використання в шаблоні бачать їх як функції (без `unknown` /
+TS18046). Ручний `.d.ts` не потрібен.
+
+---
+
+## Що відправляється на API
+
+Нічого не відправляється, доки не станеться помилка. Пакет тримає в памʼяті
+ring buffer breadcrumbs, поки користувач взаємодіє; при перехопленні помилки він
+знімає снапшот цього ланцюжка, ставить помилку в чергу і (після debounce) POSTить
+**батч**.
+
+Батч має дві частини: **`meta`** (раз на батч, застосовується до всіх помилок у
+ньому) і **`errors`** (масив перехоплених помилок).
+
+### `meta` (раз на батч)
+
+| Поле         | Тип      | Джерело | Нотатки |
+| ------------ | -------- | ------- | ------- |
+| `device`     | `object` | `navigator` / `window` | `userAgent`, `language`, `platform`, `screen` (`ШxВ`), `viewport` (`ШxВ`), `online` (bool), `memory` (`deviceMemory`, ГБ або `null`), `connection` (`effectiveType` або `null`). Сервер обрізає JSON до 2 КБ. |
+| `userId`     | `string` \| `null` | cookie `user_id` | Читається з cookie `user_id`, якщо є, інакше `null`. Пакет ніколи не вигадує id. Макс. 100 символів. |
+| `appVersion` | `string` | ваша опція `appVersion` | Дефолт `'unknown'`. Макс. 50 символів. |
+
+### `errors[]` (на кожну перехоплену помилку)
+
+| Поле          | Тип       | Опис | Ліміт |
+| ------------- | --------- | ---- | ----- |
+| `message`     | `string`  | Повідомлення помилки. | ≤ 1000 симв. |
+| `stack`       | `string`  | Стек-трейс. | ≤ 8000 симв. |
+| `source`      | `string`  | Звідки: `vue`, `window`, `promise`, `fetch` чи `console`. | ≤ 20 симв. |
+| `level`       | `string`  | Серйозність: `fatal` \| `error` \| `warning` \| `info` \| `debug`. | одне зі списку |
+| `url`         | `string`  | `window.location.href` на момент перехоплення. | ≤ 2000 симв. |
+| `route`       | `string`  | Nuxt-route `fullPath`. | ≤ 500 симв. |
+| `occurredAt`  | `string`  | ISO-8601 timestamp. | ISO-8601 |
+| `breadcrumbs` | `Breadcrumb[]` | Ланцюжок, що привів до помилки (нижче). | ≤ 50 елементів |
+
+Кожен **`Breadcrumb`**:
+
+| Поле        | Тип      | Опис | Ліміт |
+| ----------- | -------- | ---- | ----- |
+| `type`      | `string` | `click`, `input`, `navigation`, `fetch`, `console` чи ваш кастомний тип. | ≤ 30 симв. |
+| `category`  | `string` | напр. `ui.click`, `ui.input`, `navigation`, `http`, `console`. | ≤ 60 симв. |
+| `message`   | `string` | Людиночитний рядок, напр. `POST /api/pay → 500`. | ≤ 500 симв. |
+| `level`     | `string` | `info` \| `error` \| … | ≤ 20 симв. |
+| `timestamp` | `string` | ISO-8601. | ISO-8601 |
+| `data`      | `object` | Опційний структурований payload (деталі fetch: метод, статус, тайминг, заголовки, тіла запиту/відповіді). | JSON |
+
+**Ліміти батча:** щонайбільше **20 помилок на запит**; клієнт також повертає в
+чергу невдалі батчі (обмежено 200 у памʼяті) і дедуплікує *ту саму* помилку до
+`maxPerSession` (5) occurrences за сесію, тож одна повторювана помилка не
+затопить вашу квоту.
+
+---
+
+## Формат передачі та типи даних
+
+Payloadʼи кодуються у **protobuf** (proto3) і POSTяться як
+`application/x-protobuf`. Енкодер саморобний і **без залежностей** — жодного
+`protobufjs`, тож споживачам не потрібні ні Vite `optimizeDeps`, ні
+CJS-interop-конфіг.
+
+Схема (номери полів визначальні — вони мусять збігатися з декодером API):
+
+```proto
+message Breadcrumb {
+  string type      = 1;
+  string category  = 2;
+  string message   = 3;
+  string level     = 4;
+  string timestamp = 5;
+  string data      = 6;  // обʼєкт у вигляді JSON-рядка
+}
+
+message Error {
+  string message           = 1;
+  string stack             = 2;
+  string source            = 3;
+  string url               = 4;
+  string route             = 5;
+  string userId            = 6;  // per-error override (цим клієнтом не використовується)
+  string appVersion        = 7;  // per-error override (цим клієнтом не використовується)
+  string device            = 8;  // per-error override (цим клієнтом не використовується)
+  string occurredAt        = 9;
+  repeated Breadcrumb breadcrumbs = 10;
+  string level             = 11;
+}
+
+message Meta  { string device = 1; string userId = 2; string appVersion = 3; }
+message Batch { Meta meta = 1; repeated Error errors = 2; }
+```
+
+`device` і breadcrumb `data` — обʼєкти, тож їдуть як **JSON-рядки** всередині
+protobuf. Порожні рядки опускаються (дефолт proto3). Бінарне обрамлення лише
+тримає мережеву панель охайною — це **не** шифрування; схема публічна, тож
+будь-хто з нею може декодувати payload.
+
+### Як передається
+
+- Звичайний шлях: `fetch(endpoint, { method: 'POST', headers: { 'Content-Type':
+  'application/x-protobuf', 'X-Public-Key': <ключ> }, body: <bytes>, keepalive:
+  true })`.
+- Шлях page-hide: черга примусово скидається через `navigator.sendBeacon(endpoint
+  + '?key=<ключ>', Blob)` — оскільки beacon не може ставити заголовки, ключ їде в
+  query-параметрі `?key=`. Відкат до `fetch(..., { keepalive: true })`, якщо
+  `sendBeacon` недоступний чи відмовив.
+
+API також приймає звичайний JSON на тому самому endpoint (та сама валідація), що
+зручно для скриптових тестових POSTів, але SDK завжди шле protobuf.
+
+---
+
+## Перегляд і контроль ваших логів
+
+Сенс власного endpoint: після відправки пакетом **ви** володієте даними і керуєте
+ними повністю зі свого дашборда — без сторонньої консолі.
+
+- **Перегляд** — відкрийте **Logs** на проєкті, щоб побачити групи помилок, кожну
+  з повідомленням, лічильником, first/last seen, зачепленими routes і
+  стек-трейсом + breadcrumb-ланцюжком на кожну occurrence (включно з захопленими
+  fetch payload/response, коли `captureFetchDetails` увімкнено).
+- **Дедуплікація** — API групує occurrences за **fingerprint** (хеш нормалізованого
+  повідомлення + верхні стек-фрейми), тож повторювана помилка — це один рядок із
+  лічильником, а не тисячі дублікатів.
+- **Rate-ліміт і origins** — кожен проєкт має власний per-minute rate-ліміт і
+  allowlist origins. Звузьте origins, щоб відкидати сторонній трафік; самого
+  ключа недостатньо, щоб дані зайшли з неперелічeного origin.
+- **Retention** — occurrences видаляються після вікна retention (за замовчуванням
+  7 днів на сервері), тож сховище лишається обмеженим без жодних дій з вашого
+  боку.
+
+Оскільки ключ — лише на запис, а читання під логіном, публікація ключа у
+клієнтському бандлі не відкриває жодних збережених даних.
+
+---
+
+## Приватність
+
+Click-breadcrumbs записують елемент (tag / id / class / короткий текст / `data-*`
+атрибути) — **ніколи значення полів**. Нічого не захоплюється, доки не станеться
+помилка; breadcrumbs живуть лише в памʼяті і їдуть прикріпленими до помилки.
+
+Значення полів захоплюються **лише** коли ви явно вмикаєте `captureInputs: true`.
+Навіть тоді чутливі поля маскуються (зберігаються як `[masked, N chars]`, ніколи
+у відкритому вигляді): будь-який `type="password"`, а також поля, чиї `name` /
+`id` / `autocomplete` збігаються з `pass`, `secret`, `token`, `otp`, `cvv`,
+`card`, `iban`, `ssn`, `pin`, `auth` тощо. Нечутливі значення обрізаються до 100
+символів.
+
+Захоплення деталей fetch (`captureFetchDetails`, увімкнено за замовчуванням)
+редагує чутливі заголовки запиту/відповіді (`authorization`, `cookie`,
+`x-api-key`, CSRF-токени, …) і обрізає тіла до 2 КБ. Поставте `false`, якщо не
+хочете, щоб payloadʼи запитів чи тіла відповідей взагалі покидали браузер.
+
+---
+
+## Ліцензія
+
+[PolyForm Shield 1.0.0](./LICENSE) — source-available. Безкоштовно ставити й
+використовувати для будь-якої мети, **окрім** створення продукту, що конкурує з
+цим ПЗ або з тим, що ліцензіар надає з його допомогою. Не можна форкнути у
+конкурента. Повні умови у [`LICENSE`](./LICENSE); авторські права лишаються за
+автором.

package/dist/module.d.mts

@@ -6,12 +6,11 @@ interface ModuleOptions {
     /** Wrap window.fetch to capture failed requests (network errors + 5xx). Default true. */
     captureFetch?: boolean;
     /**
-     * On a failed request (HTTP >= 400 or a network error), attach full request/
-     * response detail (method, url, status, timing, headers, bodies) to the fetch
-     * breadcrumb's `data` for precise debugging. Sensitive headers (authorization/
-     * cookie/…) are redacted; bodies are truncated. Only failed requests carry
-     * detail — successful ones stay lightweight. Default true; set false to keep
-     * fetch breadcrumbs message-only (e.g. to avoid capturing request payloads).
+     * Attach full request/response detail (method, url, status, timing, headers,
+     * request payload, response body) to every fetch breadcrumb's `data` for
+     * precise debugging. Sensitive headers (authorization/cookie/…) are redacted;
+     * bodies are truncated. Default true; set false to keep fetch breadcrumbs
+     * message-only (e.g. to avoid capturing request payloads / PII).
      */
     captureFetchDetails?: boolean;
     /** Patch console.error to capture logged-but-not-thrown errors. Default true. */
@@ -22,8 +21,34 @@ interface ModuleOptions {
      * masked. Default false — opt in, since it can capture user-entered data.
      */
     captureInputs?: boolean;
-    /** Debounce before a batch is flushed, in ms. Default 2000. */
+    /**
+     * How often batches leave the browser (debounce before a flush), in ms.
+     * A flush is scheduled `flushDelay` after the first queued error; more errors
+     * arriving in that window ride the same batch. Default 2000.
+     */
     flushDelay?: number;
+    /**
+     * Floor on the spacing between consecutive flushes, in ms. Unlike `flushDelay`
+     * (a per-batch debounce), this throttles the *rate* of network requests during
+     * a sustained error storm: a flush never fires sooner than `minFlushInterval`
+     * after the previous one. Default 0 (off — `flushDelay` alone governs cadence).
+     */
+    minFlushInterval?: number;
+    /**
+     * Client-side sampling: fraction (0..1) of captured errors to actually send;
+     * the rest are dropped before they ever queue. 1 = send everything (default),
+     * 0.3 = keep ~30%. Thins volume at the source so a high-traffic app doesn't
+     * flood the per-project server rate limit. Applied per occurrence, before the
+     * per-session dedup — so with a low rate even a rare error may be dropped.
+     */
+    sampleRate?: number;
+    /**
+     * Client-side hard cap on errors *queued* per rolling minute (fixed window);
+     * anything over is dropped. Mirrors the server's per-project rate limit so the
+     * browser stops emitting instead of shipping batches that get rejected.
+     * Default 0 (off — unlimited).
+     */
+    maxPerMinute?: 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). */

package/dist/module.d.ts

@@ -6,12 +6,11 @@ interface ModuleOptions {
     /** Wrap window.fetch to capture failed requests (network errors + 5xx). Default true. */
     captureFetch?: boolean;
     /**
-     * On a failed request (HTTP >= 400 or a network error), attach full request/
-     * response detail (method, url, status, timing, headers, bodies) to the fetch
-     * breadcrumb's `data` for precise debugging. Sensitive headers (authorization/
-     * cookie/…) are redacted; bodies are truncated. Only failed requests carry
-     * detail — successful ones stay lightweight. Default true; set false to keep
-     * fetch breadcrumbs message-only (e.g. to avoid capturing request payloads).
+     * Attach full request/response detail (method, url, status, timing, headers,
+     * request payload, response body) to every fetch breadcrumb's `data` for
+     * precise debugging. Sensitive headers (authorization/cookie/…) are redacted;
+     * bodies are truncated. Default true; set false to keep fetch breadcrumbs
+     * message-only (e.g. to avoid capturing request payloads / PII).
      */
     captureFetchDetails?: boolean;
     /** Patch console.error to capture logged-but-not-thrown errors. Default true. */
@@ -22,8 +21,34 @@ interface ModuleOptions {
      * masked. Default false — opt in, since it can capture user-entered data.
      */
     captureInputs?: boolean;
-    /** Debounce before a batch is flushed, in ms. Default 2000. */
+    /**
+     * How often batches leave the browser (debounce before a flush), in ms.
+     * A flush is scheduled `flushDelay` after the first queued error; more errors
+     * arriving in that window ride the same batch. Default 2000.
+     */
     flushDelay?: number;
+    /**
+     * Floor on the spacing between consecutive flushes, in ms. Unlike `flushDelay`
+     * (a per-batch debounce), this throttles the *rate* of network requests during
+     * a sustained error storm: a flush never fires sooner than `minFlushInterval`
+     * after the previous one. Default 0 (off — `flushDelay` alone governs cadence).
+     */
+    minFlushInterval?: number;
+    /**
+     * Client-side sampling: fraction (0..1) of captured errors to actually send;
+     * the rest are dropped before they ever queue. 1 = send everything (default),
+     * 0.3 = keep ~30%. Thins volume at the source so a high-traffic app doesn't
+     * flood the per-project server rate limit. Applied per occurrence, before the
+     * per-session dedup — so with a low rate even a rare error may be dropped.
+     */
+    sampleRate?: number;
+    /**
+     * Client-side hard cap on errors *queued* per rolling minute (fixed window);
+     * anything over is dropped. Mirrors the server's per-project rate limit so the
+     * browser stops emitting instead of shipping batches that get rejected.
+     * Default 0 (off — unlimited).
+     */
+    maxPerMinute?: 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). */

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "nuxt-error-tracker",
   "configKey": "errorTracker",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "builder": {
     "@nuxt/module-builder": "0.8.4",
     "unbuild": "2.0.0"

package/dist/module.mjs

@@ -4,6 +4,14 @@ function posInt(value, fallback) {
   const n = Number(value);
   return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
 }
+function clamp01(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.min(Math.max(n, 0), 1) : fallback;
+}
+function nonNegInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
 const module = defineNuxtModule({
   meta: {
     name: "nuxt-error-tracker",
@@ -19,6 +27,9 @@ const module = defineNuxtModule({
     captureConsole: true,
     captureInputs: false,
     flushDelay: 2e3,
+    minFlushInterval: 0,
+    sampleRate: 1,
+    maxPerMinute: 0,
     maxPerSession: 5,
     maxBatch: 20,
     maxBreadcrumbs: 30
@@ -35,6 +46,9 @@ const module = defineNuxtModule({
       captureConsole: options.captureConsole !== false,
       captureInputs: options.captureInputs === true,
       flushDelay: posInt(options.flushDelay, 2e3),
+      minFlushInterval: nonNegInt(options.minFlushInterval, 0),
+      sampleRate: clamp01(options.sampleRate, 1),
+      maxPerMinute: nonNegInt(options.maxPerMinute, 0),
       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),

package/dist/runtime/plugin.client.js

@@ -11,12 +11,29 @@ export default defineNuxtPlugin((nuxtApp) => {
   if (!config || !config.endpoint || !config.publicKey) return;
   const route = useRoute();
   const FLUSH_DELAY = config.flushDelay ?? 2e3;
+  const MIN_FLUSH_INTERVAL = config.minFlushInterval ?? 0;
+  const SAMPLE_RATE = config.sampleRate ?? 1;
+  const MAX_PER_MINUTE = config.maxPerMinute ?? 0;
   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;
+  let lastFlushAt = 0;
+  let rateWindowStart = 0;
+  let rateWindowCount = 0;
+  function rateLimited() {
+    if (!MAX_PER_MINUTE) return false;
+    const now = Date.now();
+    if (now - rateWindowStart >= 6e4) {
+      rateWindowStart = now;
+      rateWindowCount = 0;
+    }
+    if (rateWindowCount >= MAX_PER_MINUTE) return true;
+    rateWindowCount++;
+    return false;
+  }
   const crumbs = [];
   function addCrumb(c) {
     crumbs.push({ ...c, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
@@ -43,6 +60,7 @@ export default defineNuxtPlugin((nuxtApp) => {
   const MAX_QUEUE = 200;
   function flush(useBeacon = false) {
     if (!queue.length) return;
+    lastFlushAt = Date.now();
     try {
       const batch = queue.splice(0, MAX_BATCH);
       const body = {
@@ -78,18 +96,22 @@ export default defineNuxtPlugin((nuxtApp) => {
   }
   function scheduleFlush() {
     if (flushTimer) return;
+    const sinceLast = Date.now() - lastFlushAt;
+    const wait = Math.max(FLUSH_DELAY, MIN_FLUSH_INTERVAL - sinceLast);
     flushTimer = setTimeout(() => {
       flushTimer = null;
       flush();
-    }, FLUSH_DELAY);
+    }, wait);
   }
   function capture(err, source, level = "error") {
     try {
       const error = err instanceof Error ? err : new Error(String(err));
       if (error.message === "Script error.") return;
+      if (SAMPLE_RATE < 1 && Math.random() >= SAMPLE_RATE) return;
       const key = sessionKey(error.message, error.stack ?? "");
       const count = sessionCounts.get(key) ?? 0;
       if (count >= MAX_PER_SESSION) return;
+      if (rateLimited()) return;
       sessionCounts.set(key, count + 1);
       queue.push({
         message: error.message.slice(0, 1e3),
@@ -266,7 +288,7 @@ export default defineNuxtPlugin((nuxtApp) => {
         if (!isOwn) {
           const failed = res.status >= 400;
           let data;
-          if (failed && config.captureFetchDetails) {
+          if (config.captureFetchDetails) {
             data = {
               method,
               url: reqUrl,

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "nuxt-error-tracker",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
+  "license": "PolyForm-Shield-1.0.0",
   "exports": {
     ".": {
       "types": "./dist/types.d.ts",