@dasasian/firebase-structured-logger 0.8.0 → 1.0.0

package/README.md

@@ -17,8 +17,8 @@ Your web app crashed at `app-4f2a.js:1:98432`. This tells you it was `Checkout.t
 
 Ships a browser logger, a server logger, and the `fsl` CLI. Built for Firebase, but
 Firebase is optional: the browser half has no Firebase dependency, and the server half
-runs on Cloud Functions, Cloud Run, or any Node server. What it needs is a Google Cloud
-project — that is where the logs live.
+runs on Cloud Functions, Cloud Run, or any Node server on Google Cloud, where stdout goes
+to Cloud Logging. What it needs is a Google Cloud project — that is where the logs live.
 
 ## One query, both halves
 
@@ -66,11 +66,23 @@ npm install @dasasian/firebase-structured-logger
 # Cloud Functions
 cd functions && npm install @dasasian/firebase-structured-logger
 
-# Cloud Run, or any Node server
+# Cloud Run, or any Node server on Google Cloud
 npm install @dasasian/firebase-structured-logger
 ```
 
-Ships ESM with three entry points — `/client`, `/functions`, `/tools` — plus the `fsl` CLI. `firebase`, `firebase-admin`, and `firebase-functions` are optional peer dependencies (bring your own versions). None of them is needed to load the package; each only switches on the part that uses it — see [Without Firebase](#without-firebase).
+Ships CommonJS with TypeScript types — works from `require` and from `import`, in Node and in any bundler — with three entry points, `/client`, `/functions` and `/tools`, plus the `fsl` CLI. `firebase`, `firebase-admin`, and `firebase-functions` are optional peer dependencies (bring your own versions). None of them is needed to load the package; each only switches on the part that uses it — see [Without Firebase](#without-firebase).
+
+Installing next to **firebase-admin 13** in one command can leave two copies of
+`@google-cloud/storage` (8 for this package, 7 for firebase-admin). Both work; run
+`npm dedupe` once and npm keeps the one they share. firebase-admin 14.5 and later use
+the same Storage as this package, so there is nothing to do.
+
+### Upgrading from 0.x
+
+Nothing breaks. Eight names were renamed for the 1.0 API — `minLogLevel` became
+`minSeverity`, `bucketName` became `bucket`, and so on — and each old name still works in
+1.x, with a one-time console warning naming its replacement. They are removed in 2.0.
+The full list is in [Renamed in 1.0](#client). Run `npx fsl doctor` after upgrading.
 
 ## Setup
 
@@ -113,7 +125,7 @@ import { initLogger, createClientLogFunction } from '@dasasian/firebase-structur
 initLogger({ appId: 'my-app' })
 
 export const logFrontendEvent = createClientLogFunction({
-  bucketName: 'my-app.firebasestorage.app', // holds source maps AND attachments
+  bucket: 'my-app.firebasestorage.app', // holds source maps AND attachments
 })
 ```
 
@@ -126,13 +138,13 @@ gs://my-app.firebasestorage.app/logAttachments/{logId}/{name}
 
 Both the bucket and the prefix can be changed per half — see [Source maps](#source-maps)
 for `sourceMaps: { bucket, prefix }`, and [Attachments](#attachments) for
-`configureAttachments({ bucket, prefix })`. Omit `bucketName` entirely and both fall back
+`configureAttachments({ bucket, prefix })`. Omit `bucket` entirely and both fall back
 to your project's default bucket.
 
 **3. Wire the deploy script** — upload source maps and strip them from the hosting bundle as part of deploy. Merge into your root `package.json` scripts, keeping any existing flags like `--project`:
 
 ```json
-"deploy": "export VITE_RELEASE_ID=$(git rev-parse --short HEAD) && npm run build && npx fsl upload-sourcemaps --functions=./functions --embed-sourcemaps && firebase deploy"
+"deploy": "export VITE_RELEASE_ID=$(git rev-parse --short HEAD) && npm run build && npx fsl upload-sourcemaps --backend=./functions --embed-sourcemaps && firebase deploy"
 ```
 
 `fsl upload-sourcemaps` reads the bucket from `VITE_FIREBASE_STORAGE_BUCKET` (or `FIREBASE_STORAGE_BUCKET`) after loading `.env.local`. It uploads source maps to Cloud Storage, embeds a copy in `functions/sourcemaps/current/` for fast lookup, and deletes them from `dist/` so they are **not** served to browsers.
@@ -142,9 +154,9 @@ to your project's default bucket.
 **4. Verify it works** — prove the round trip before you trust it:
 
 ```ts
-import { triggerTestLog } from '@dasasian/firebase-structured-logger/client'
+import { sendTestLog } from '@dasasian/firebase-structured-logger/client'
 
-triggerTestLog() // wire to a dev-only button; sends one error, one warning, one info
+sendTestLog() // wire to a dev-only button; sends one error, one warning, one info
 ```
 
 Look for `labels.errorType="fsl-verify"` — in Cloud Logging once deployed, or in `dev.jsonl`
@@ -198,7 +210,7 @@ The entry should carry `userId` without your having written it.
 
 ### If your backend is not Cloud Functions
 
-Cloud Run, or any Node server you already run. Two things differ from the browser
+Cloud Run, or any Node server you already run on Google Cloud. Two things differ from the browser
 path above; everything else — breadcrumbs, labels, symbolication, the free fields — is
 identical, and the entries land in the same stream in the same shape.
 
@@ -215,7 +227,7 @@ const app = express()
 app.use(express.json({ limit: '10mb' }))   // attachments ride in the body
 
 app.post('/log', createHttpLogHandler({
-  bucketName: 'my-app.firebasestorage.app', // holds source maps AND attachments
+  bucket: 'my-app.firebasestorage.app', // holds source maps AND attachments
   authorize: async (req) => {
     const header = String(req.headers.authorization ?? '')
     if (!header.startsWith('Bearer ')) return false
@@ -279,11 +291,14 @@ initLogger({
 
 Nothing here needs a Firebase project — only a Google Cloud one. What changes:
 
+- **The server has to run on Google Cloud** — Cloud Run, GKE, App Engine, or Compute
+  Engine with the Ops Agent. Entries are written to stdout, and only there does stdout
+  reach Cloud Logging. On AWS, Vercel or your own box they print and go nowhere.
 - **The browser** needs no `firebase` package. `logFunction` is the `fetch` above; send
   whatever credential your app already uses.
 - **`authorize`** checks your own session instead of a Firebase ID token — for example
   `authorize: (req) => sessions.isValid(req.headers.cookie)`.
-- **Storage** has no Firebase default bucket to fall back to. Name one with `bucketName`
+- **Storage** has no Firebase default bucket to fall back to. Name one with `bucket`
   (it holds source maps and attachments), and give the service's account access to it.
   Or name none: embedded maps still resolve the current release, older releases stay
   minified, and attachments are dropped — the log says so once.
@@ -325,7 +340,7 @@ A gate that throws counts as a rejection, not an opening.
   the trace id is still written, but does not join the platform's request log.
 - **No `firebase-admin`? Also optional.** Storage is only needed for older releases'
   source maps and for attachments. With `firebase-admin` installed, its Storage and
-  default bucket are used. Without it, name the bucket — `bucketName` on the handler, or
+  default bucket are used. Without it, name the bucket — `bucket` on the handler, or
   `configureAttachments({ bucket })` — and the service's own credentials are used.
 - **No Storage bucket?** You do not need one. `fsl upload-sourcemaps --embed-sourcemaps`
   without `--bucket` embeds the current release's maps into your deploy and uploads
@@ -336,6 +351,75 @@ A gate that throws counts as a rejection, not an opening.
 - **Response codes:** `204` written, `400` malformed payload, `401` gate refused, `405`
   not a POST, `500` something else. The client treats a non-2xx as a throw.
 
+## Check your setup
+
+Most of what can go wrong here goes wrong silently: logs that never arrive, stacks that
+never resolve, source code published next to the app. `fsl doctor` reads the project from
+disk and says what it finds. It needs no network and no credentials, and it only reports
+facts it can read from a file — it never guesses from your source code, so a finding is
+never a false alarm.
+
+```bash
+npx fsl doctor                                     # Firebase: reads firebase.json
+npx fsl doctor --backend=./server --dist=./dist    # anything else: say where things are
+```
+
+It prints a summary of how your setup will behave, then any findings:
+
+```
+Setup: Firebase — functions in ./functions, web build in ./dist
+
+  Logging        firebase-functions write()
+  Trace ids      from each Cloud Functions trigger
+  Storage        firebase-admin, default bucket
+  Callable       createClientLogFunction available
+
+  ⚠ duplicate-storage    2 copies of @google-cloud/storage (8.2.0 at the top level, 7.22.0 inside firebase-admin)
+                        Fix: npm dedupe
+```
+
+| Id | Level | Means |
+|---|---|---|
+| `maps-published` | error | `.map` files are in the folder hosting serves — your source code is public |
+| `node-version` | error | the backend's Node is below 22 |
+| `callable-without-firebase-functions` | error | `firebase.json` has functions, but `firebase-functions` is not installed there |
+| `could-not-check` | error | doctor could not read something it needed — including "run `npm install` first" |
+| `duplicate-storage` | warning | two copies of `@google-cloud/storage`; fix with `npm dedupe` |
+| `unsupported-peer` | warning | an installed peer (`firebase-admin`, `firebase-functions`, `firebase`) is outside the supported range |
+| `embedded-maps-without-release` | warning | maps are embedded without a `.release` marker, so an older release can resolve against the wrong map |
+
+**Exit code:** `0` when there are no errors, `1` when there is one. `--strict` also fails on
+warnings, for teams that want a spotless setup; without it, a deliberate choice like
+running with no Storage does not break CI. A check doctor could not run is always an
+error, never a pass.
+
+**`--json`** prints the same result for scripts and agents:
+
+```json
+{
+  "setup": { "kind": "firebase", "backend": "./functions", "dist": "./dist",
+             "logging": "firebase-functions", "trace": "trigger", "storage": "firebase-admin",
+             "callable": true },
+  "findings": [
+    { "id": "duplicate-storage", "level": "warning",
+      "message": "2 copies of @google-cloud/storage (8.2.0 at the top level, 7.22.0 inside firebase-admin)",
+      "fix": "npm dedupe" }
+  ],
+  "exitCode": 0
+}
+```
+
+`setup.kind` is `firebase`, `node`, `browser-only` or `backend-only`; `logging` is
+`firebase-functions`, `stdout` or `none`; `trace` is `trigger`, `header` or `none`; and
+`storage` is `firebase-admin`, `google-cloud-storage` (which still needs a bucket named in
+your code — doctor cannot see it) or `none`. The ids and fields are part of the 1.0 API:
+scripts may depend on them.
+
+What doctor does not check: anything set in your own code — the release id you pass to
+`initLogger`, a bucket name passed to a handler. Its Storage line says so — "needs a bucket named in code (not checked)" — rather than
+guessing. [`fsl verify`](https://github.com/dasasian/firebase-structured-logger/issues/25),
+planned after 1.0, will check those by sending a real log.
+
 ## Local development
 
 The Functions emulator writes the same entries to a local JSONL file instead of Cloud
@@ -439,6 +523,12 @@ logger.error(err, { orderId })
 | resolved file and line | function | your source maps — `Checkout.tsx:42`, not `app-4f2a.js:1:98432` |
 | trace context | function | request correlation in Cloud Logging |
 
+**Repeats are counted, not thrown away.** The usual answer to an error that fires 200 times
+is to send the first few and drop the rest. This one sends 3 in full, counts the other 197,
+and tells you when it started, when it stopped, which release and which user. Close the tab
+and the count waits on the device for the next visit. See
+[Repeats are counted, not dropped](#repeats-are-counted-not-dropped).
+
 Backend logs get the same treatment: `withLogging` attaches `functionName`, `userId` from
 the verified `request.auth.uid`, and whatever else you bind.
 
@@ -600,7 +690,7 @@ labels.hasAttachments="true"     # entries that have files
 labels.logId="01J..."            # the entry whose files you are looking for
 ```
 
-By default they share the bucket passed to `createClientLogFunction({ bucketName })` — the
+By default they share the bucket passed to `createClientLogFunction({ bucket })` — the
 same one the source maps live in, falling back to the project's default bucket.
 
 Send them somewhere else with `configureAttachments`, in your functions entry point:
@@ -622,16 +712,34 @@ or different IAM from your source maps — none of which can be arranged with a
 Nothing expires them. Add a lifecycle rule on `logAttachments/` to delete after N days, or
 they accumulate for the life of the project.
 
+## Big entries
+
+Cloud Functions and Cloud Run both cut a stdout/stderr log line at exactly **102,400 bytes**
+(100 KiB) — measured live. Past that the entry does not arrive truncated-but-valid: it arrives
+as broken plain text, with no `severity`, no labels, and nothing for Error Reporting to group.
+
+The backend logger watches for this. An entry over 90 KiB is shortened before it is written —
+breadcrumb data first, then other context, then the tail of a long stack (the top frames are
+what Error Reporting groups on, so those survive longest), then long text fields, and label
+values only as a last resort. `severity`, labels, the trace and `serviceContext` are never
+touched.
+
+The full, unshortened entry is saved to Cloud Storage as `fsl-overflow.json`, at the same
+`logAttachments/{logId}/` path an ordinary attachment would use, whenever a bucket is
+available — see [Attachments](#attachments). A shortened entry carries `labels.truncated="true"`,
+and `labels.hasAttachments="true"` when the full entry was saved. With no Storage configured,
+the entry is still shortened; the original is lost, and the process warns once, not per entry.
+
 ## Volume controls
 
-Three separate gates decide whether a log is written. All have defaults, and the defaults
-drop things — so this is worth reading before you conclude something is broken.
+Several gates decide whether a log is written. All have defaults, and the defaults
+hold things back — so this is worth reading before you conclude something is broken.
 
 | Gate | Default | Where |
 |---|---|---|
-| Session limit | **50 logs**, then the client stops sending | client, per browser session |
-| Duplicate limit | **3 copies** of the same error, then it stops | client, per browser session |
-| Client severity floor | `WARNING` in production, `DEBUG` in dev | client, `minLogLevel` |
+| Log limit | bursts of up to **50 logs**, then **one log recharges every 60 s**; the last **10** for errors only | client, per browser tab |
+| Duplicates | **3** full copies of the same error, then counted and sent as a summary | client, per browser tab |
+| Client severity floor | `WARNING` in production, `DEBUG` in dev | client, `minSeverity` |
 | Server severity floor | `WARNING` in production, `DEBUG` in the emulator | function, `minSeverity` |
 | Function concurrency | `maxInstances: 1` on `createClientLogFunction` | function |
 
@@ -640,32 +748,98 @@ initLogger({
   appId: 'my-app',
   releaseId,
   logFunction,
-  minLogLevel: 'INFO',
-  rateLimitOptions: { sessionLimit: 200, duplicateLimit: 5 },
+  minSeverity: 'INFO',
+  rateLimitOptions: {
+    burstLimit: 50,              // how many logs can go at once
+    rechargeSecondsPerLog: 60,   // after a burst, one log recharges every 60 seconds
+    reservedForErrors: 10,       // of the burst, how many only ERROR and above may use
+    duplicateLimit: 3,       // full copies of one error before counting starts
+    summaryIntervalMinutes: 60,
+    summaryMaxAgeDays: 7,    // how long an unsent summary waits on the device
+    maxPendingSummaries: 50,
+  },
 })
 ```
 
-Two errors count as duplicates when the **message and the screen both match**, so the same
-error on two different screens is not collapsed into one. The budget lives in
-`sessionStorage` and resets with the session.
-
 The client's production default comes from `process.env.NODE_ENV`, which Vite replaces at
 build time. A `define: { 'process.env': {} }` in `vite.config` — common, to quiet a library
 that expects Node — replaces the whole object instead, `NODE_ENV` reads as undefined, and
 the floor is silently `DEBUG` in production. If your config has that line, pass
-`minLogLevel` explicitly. Stating it is the safe habit either way: it is the one default
+`minSeverity` explicitly. Stating it is the safe habit either way: it is the one default
 here whose failure mode is a bill rather than a missing log.
 
+### Bursts recharge
+
+Each browser tab can send a burst of up to `burstLimit` logs (50). After that, one log
+recharges every `rechargeSecondsPerLog` seconds (60) — one at a time, so a full burst takes
+50 minutes to come back. A reload does not reset it: the tab keeps its count in
+`sessionStorage`.
+
+So a burst at start-up is fine, and a user who works in the app all afternoon is never
+silenced for long. A bug that logs in a loop is still held to about 60 entries an hour per
+user: 1,000 users stuck in such a loop for a working month stays around the 50 GiB of
+Cloud Logging that each project gets free.
+
+The last `reservedForErrors` logs (10) are kept for errors: warnings can use the burst down
+to 10, and only `ERROR` and above can use the rest. A value over half of `burstLimit` is
+capped at half, with one warning, so warnings always have room. A noisy warning cannot use up the room a crash needs.
+
+### Repeats are counted, not dropped
+
+Two errors are the same when the **message and the screen both match**, so the same error
+on two different screens is kept apart. The first 3 are sent in full, with their stack and
+breadcrumbs. After that the browser only counts them, and sends one summary:
+
+```
+WARNING  Repeated 197 more times: cart sync failed
+         labels.repeatOf="<repeatKey of the first copy>"  labels.repeatCount="197"
+         labels.firstSeen="…"  labels.lastSeen="…"
+```
+
+The same count and window are in the entry's body, under `context.repeat`, so a summary is
+filed as JSON like every other entry and a search on `jsonPayload.message` finds it.
+
+The browser never learns the server's `logId` for the first copy — `writeLog` assigns it
+after the log has already left the tab. So each full copy instead carries its own
+`labels.repeatKey`, a client-side id, and the summary's `repeatOf` points at that instead:
+query `labels.repeatKey="…" OR labels.repeatOf="…"` to find a full copy and its summary
+together.
+
+A summary is sent once an hour, when the tab is hidden, and once at startup for anything
+a previous visit left queued. It is keyed by the error, the `releaseId` and the `userId`,
+so two releases or two people on one computer are never counted together. Its entry is
+timestamped at `lastSeen`, not at the time it was sent.
+
+The summary's own labels are `appId`, `releaseId`, `userId`, `screen` and `errorType` — from
+the time the errors happened, not from whoever's tab eventually sends it — plus
+`repeatOf`/`repeatCount`/`firstSeen`/`lastSeen`/`sentLate`. Everything else about the error —
+browser, platform, breadcrumbs, the stack — is not repeated here; it is already on the full
+copies `repeatOf` points back to.
+
+Unsent summaries are kept in `localStorage`, so closing the tab does not lose them: the
+next visit sends them, marked `labels.sentLate="true"`. A summary is only removed from that
+queue once it has actually been sent — a failed attempt (offline, or the tab closing right
+after it was queued) leaves it for the next flush or the next visit to retry, never twice.
+At most 50 wait, and any older than 7 days are deleted rather than sent — they are error
+messages, and may hold personal data.
+
+A summary is a `WARNING` with no stack, so Cloud Error Reporting sees the 3 full copies and
+not the summary. For the true count, add up `labels.repeatCount` in Cloud Logging.
+
+Summaries do not count against the burst. There is at most one per error, per release, per user,
+per hour.
+
 ### What a dropped log looks like
 
 The two rate limits say so in the browser console:
 
 ```
-[fsl] Duplicate suppressed: TypeError: cannot read 'id'|checkout
-[fsl] Session log limit reached
+[fsl] Duplicate counted for the next summary: TypeError: cannot read 'id' | checkout
+[fsl] Log limit reached — recharging, next log in about a minute
+[fsl] Log limit: only errors can use the reserved logs now
 ```
 
-**The severity floors are silent.** Both of them — the client's `minLogLevel` and the
+**The severity floors are silent.** Both of them — the client's `minSeverity` and the
 function's `minSeverity` — simply return, with nothing written and nothing logged about it.
 
 So if an entry never arrived and there is no `[fsl]` warning in the console, it was a floor,
@@ -674,7 +848,7 @@ not a limit. In production both default to `WARNING`, which drops `DEBUG`, `INFO
 `INFO` you expected to see has two places it can vanish.
 
 `maxInstances: 1` is a deliberate cost guard on what is usually the busiest function in the
-system. Raise it (`createClientLogFunction({ bucketName, maxInstances: 5 })`) if you are
+system. Raise it (`createClientLogFunction({ bucket, maxInstances: 5 })`) if you are
 dropping client logs under load — and watch your Cloud Logging bill when you do.
 
 Feedback is exempt from every one of these. See [User feedback](#user-feedback).
@@ -697,6 +871,9 @@ Narrow it when you need to:
 | `labels.screen="checkout"` | one screen |
 | `labels.feedback="true"` | user-reported issues |
 | `labels.hasAttachments="true"` | entries with files in GCS |
+| `labels.truncated="true"` | entries shortened to fit — the full copy is `fsl-overflow.json` |
+| `labels.repeatKey="<key>" OR labels.repeatOf="<key>"` | one repeating error: its full copies and its summaries |
+| `labels.sentLate="true"` | repeat summaries sent on a later visit |
 
 Locally, the emulator's JSONL answers the same questions. Point
 **[firebase-mcp-server](https://github.com/dasasian/firebase-mcp-server)** at either and ask
@@ -729,7 +906,21 @@ logger.addBreadcrumb(type, name, data?)
 ```
 
 Also exported: `initLogger`, `getClientLogger`, `setupGlobalErrorHandler`, `handleReactError`,
-`sendFeedback`, `triggerTestLog`, `addBreadcrumb`, `bc`.
+`sendFeedback`, `sendTestLog`, `addBreadcrumb`, `bc`.
+
+**Renamed in 1.0.** The old names still work in 1.x, each with a one-time console warning,
+and are removed in 2.0:
+
+| Old | New |
+|---|---|
+| `minLogLevel` (client `initLogger`) | `minSeverity` |
+| `bucketName` (`createClientLogHandler`, `createClientLogFunction`, `createHttpLogHandler`) | `bucket` |
+| `rateLimitOptions.sessionLimit` | `rateLimitOptions.burstLimit` |
+| `rateLimitOptions.refillPerMinute` | `rateLimitOptions.rechargeSecondsPerLog` (seconds, not a rate: `60 / refillPerMinute`) |
+| `rateLimitOptions.errorReserve` (a share) | `rateLimitOptions.reservedForErrors` (a count: `errorReserve × burstLimit`) |
+| type `ClientLogRequest` | type `LogRequest` |
+| `triggerTestLog()` | `sendTestLog()` |
+| `fsl upload-sourcemaps --functions=<dir>` | `--backend=<dir>` (it is not only for Cloud Functions) |
 
 `Logger` is exported as a **type only** — the client logger is a session singleton, so
 annotate with `Logger<MyAppLabels>` and construct with `initLogger()`. A second instance
@@ -748,7 +939,7 @@ logError / logWarn / logInfo / logDebug (message, labels?, context?, attachments
 configureAttachments({ bucket?, prefix? })    // once, at module load — see Attachments
 
 // Receiving client logs. All three take the same source-map config:
-//   { bucketName?, sourceMaps?: { bucket?, prefix? } }
+//   { bucket?, sourceMaps?: { bucket?, prefix? } }
 createClientLogFunction({ …, cors?, maxInstances? })   // a ready-to-export callable
 createHttpLogHandler({ …, authorize, allowOrigin? })   // an (req, res) handler for Express etc.
 createClientLogHandler({ … })                          // the bare handler, wrap it yourself
@@ -765,13 +956,18 @@ bare handler only if you are wrapping it in something else yourself.
 
 ```bash
 # Upload source maps to Cloud Storage and strip local .map files (run in deploy)
-npx fsl upload-sourcemaps --functions=./functions --embed-sourcemaps
+npx fsl upload-sourcemaps --backend=./functions --embed-sourcemaps
 
 # Same, to a bucket and prefix of your choosing — tell the reader the same values
-npx fsl upload-sourcemaps --functions=./functions --embed-sourcemaps --bucket=my-maps --prefix=fsl-maps
+npx fsl upload-sourcemaps --backend=./functions --embed-sourcemaps --bucket=my-maps --prefix=fsl-maps
 
 # No bucket at all: embed the current release, upload nothing
-npx fsl upload-sourcemaps --functions=./backend --embed-sourcemaps
+npx fsl upload-sourcemaps --backend=./backend --embed-sourcemaps
+
+# Check the setup from disk — no network, no credentials (see "Check your setup")
+npx fsl doctor
+npx fsl doctor --backend=./server --dist=./dist   # no firebase.json to read
+npx fsl doctor --strict --json                   # CI: fail on warnings too, machine-readable
 
 # Install the Claude Code skills into the current project (or --global, --force)
 npx fsl install-skills
@@ -832,6 +1028,9 @@ Some of what is already handled here, all of it learned the expensive way:
   disagree over a typo.
 - **Checking a rate limit and spending it as two calls double-counts**, quietly making a
   configured budget of 50 a budget of 25.
+- **A fixed budget goes silent in a long session.** 50 logs per page load is spent by
+  mid-morning in an app someone keeps open all day, and the crash at lunch is never sent.
+  A budget that refills, with a share kept for errors, does not have that shape.
 - **An old stack naming a bundle that still exists** resolves against the current release's
   map, giving line numbers that are confidently wrong — worse than none, because nothing
   signals it.

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { initLogger, getClientLogger, sendFeedback, triggerTestLog } from './logger';
+export { initLogger, getClientLogger, sendFeedback, sendTestLog, triggerTestLog } from './logger';
 export type { Logger, InitLoggerConfig, FeedbackOptions, RateLimitConfig } from './logger';
 export { setupGlobalErrorHandler, handleReactError } from './errorHandler';
 export { addBreadcrumb, bc } from './breadcrumbs';

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAMpF,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1F,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAMjG,YAAY,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AAC1F,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,eAAe,CAAA;AACjD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/client/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bc = exports.addBreadcrumb = exports.handleReactError = exports.setupGlobalErrorHandler = exports.triggerTestLog = exports.sendFeedback = exports.getClientLogger = exports.initLogger = void 0;
+exports.bc = exports.addBreadcrumb = exports.handleReactError = exports.setupGlobalErrorHandler = exports.triggerTestLog = exports.sendTestLog = exports.sendFeedback = exports.getClientLogger = exports.initLogger = void 0;
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "initLogger", { enumerable: true, get: function () { return logger_1.initLogger; } });
 Object.defineProperty(exports, "getClientLogger", { enumerable: true, get: function () { return logger_1.getClientLogger; } });
 Object.defineProperty(exports, "sendFeedback", { enumerable: true, get: function () { return logger_1.sendFeedback; } });
+Object.defineProperty(exports, "sendTestLog", { enumerable: true, get: function () { return logger_1.sendTestLog; } });
 Object.defineProperty(exports, "triggerTestLog", { enumerable: true, get: function () { return logger_1.triggerTestLog; } });
 var errorHandler_1 = require("./errorHandler");
 Object.defineProperty(exports, "setupGlobalErrorHandler", { enumerable: true, get: function () { return errorHandler_1.setupGlobalErrorHandler; } });

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;AAAA,mCAAoF;AAA3E,oGAAA,UAAU,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,wGAAA,cAAc,OAAA;AAOlE,+CAA0E;AAAjE,uHAAA,uBAAuB,OAAA;AAAE,gHAAA,gBAAgB,OAAA;AAClD,6CAAiD;AAAxC,4GAAA,aAAa,OAAA;AAAE,iGAAA,EAAE,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;AAAA,mCAAiG;AAAxF,oGAAA,UAAU,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,wGAAA,cAAc,OAAA;AAO/E,+CAA0E;AAAjE,uHAAA,uBAAuB,OAAA;AAAE,gHAAA,gBAAgB,OAAA;AAClD,6CAAiD;AAAxC,4GAAA,aAAa,OAAA;AAAE,iGAAA,EAAE,OAAA"}

package/dist/client/logger.d.ts

@@ -12,8 +12,10 @@ export interface InitLoggerConfig<AppLabels extends Record<string, string | unde
     appId: string;
     releaseId: string;
     logFunction: LogCallable;
-    minLogLevel?: LogSeverity;
+    minSeverity?: LogSeverity;
     rateLimitOptions?: RateLimitConfig;
+    /** @deprecated Use `minSeverity`. */
+    minLogLevel?: LogSeverity;
 }
 export declare class Logger<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>> {
     private readonly config;
@@ -46,6 +48,22 @@ export declare class Logger<AppLabels extends Record<string, string | undefined>
      */
     sendFeedback(text: string, extras?: FeedbackOptions<AppLabels>): void;
     private send;
+    private readonly summariesInFlight;
+    /** Send whatever repeat summaries are due, from this visit or an earlier one. */
+    sendPendingSummaries(): void;
+    /**
+     * A repeat summary: a WARNING with no stack, timestamped at `lastSeen` (see
+     * README, "Repeats are counted, not dropped"). It still respects the
+     * severity floor — only the budget and the duplicate gate are skipped, via
+     * `send`'s `skipBudget`.
+     *
+     * It is queued in `localStorage` precisely so a failed send does not lose
+     * it — offline, or the tab tearing down right after the `visibilitychange`
+     * that triggered this. So it is only acknowledged (removed from the queue)
+     * once `send` reports the entry actually reached `logFunction`; otherwise
+     * the next flush, or the next visit, finds it still there and retries it.
+     */
+    private sendRepeatSummary;
 }
 /**
  * Send user feedback through the configured logger.
@@ -55,7 +73,7 @@ export declare class Logger<AppLabels extends Record<string, string | undefined>
  */
 export declare function sendFeedback<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>>(text: string, extras?: FeedbackOptions<AppLabels>): void;
 /**
- * Trigger a test log entry to verify the logging pipeline is working end-to-end.
+ * Send a test log entry to verify the logging pipeline is working end-to-end.
  * Logs at all severities with errorType: 'fsl-verify'. Safe to call in dev only.
  *
  * After clicking, check:
@@ -63,6 +81,8 @@ export declare function sendFeedback<AppLabels extends Record<string, string | u
  * 2. Stack trace is symbolicated (points to source file, not minified bundle)
  * 3. MCP query: source: local, where: [{ field: "labels.errorType", operator: "==", value: "fsl-verify" }]
  */
+export declare function sendTestLog(): void;
+/** @deprecated Use `sendTestLog()`. */
 export declare function triggerTestLog(): void;
 export declare function initLogger<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>>(config: InitLoggerConfig<AppLabels>): Logger<AppLabels>;
 export declare function getClientLogger<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>>(): Logger<AppLabels>;

package/dist/client/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/client/logger.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/client/logger.ts"],"names":[],"mappings":"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"}