@dasasian/firebase-structured-logger 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dasasian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dasasian/firebase-structured-logger/main/assets/hero.svg" alt="firebase-structured-logger — structured logging for Firebase apps" width="900">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dasasian/firebase-structured-logger"><img alt="npm" src="https://img.shields.io/npm/v/@dasasian/firebase-structured-logger?style=flat-square&color=235a9b"></a>
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-235a9b?style=flat-square"></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square">
+  <img alt="Node 18+" src="https://img.shields.io/badge/node-18%2B-5fa04e?style=flat-square">
+</p>
+
+# @dasasian/firebase-structured-logger
+
+One logging pipeline for a Firebase app, from the browser to Google Cloud Logging: frontend events go to a Cloud Function, production stack traces are **symbolicated** against your source maps, and everything is written as **structured, queryable entries**. Ships a client logger, a Cloud Functions logger, and an `fsl` CLI.
+
+## Why
+
+- **Symbolicated frontend errors** — minified production traces resolve back to `File.tsx:line:col` using source maps you upload at deploy time. No more chasing `app-4f2a.js:1:98432`.
+- **Structured entries** — severity, labels, user / session / screen context, breadcrumbs, and file attachments, all queryable in Cloud Logging.
+- **One API across surfaces** — the same `logger.info/warning/error/debug` shape on the client and in Cloud Functions.
+- **Local dev loop** — the Functions emulator writes JSONL you can `tail` or query without deploying — and query from Claude with the companion [**firebase-mcp-server**](https://github.com/dasasian/firebase-mcp-server).
+
+## Install
+
+```bash
+# frontend (project root)
+npm install @dasasian/firebase-structured-logger
+
+# Cloud Functions
+cd functions && 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).
+
+## Quick start
+
+**1. Initialize the client** — at your app entry (e.g. `src/main.tsx`), before any logging:
+
+```ts
+import { initLogger, setupGlobalErrorHandler } from '@dasasian/firebase-structured-logger/client'
+import { httpsCallable } from 'firebase/functions'
+import { functions } from './config/firebase'
+
+export const logger = initLogger({
+  appId: 'my-app',
+  releaseId: import.meta.env.VITE_RELEASE_ID ?? 'dev',
+  logFunction: httpsCallable(functions, 'logFrontendEvent'),
+})
+
+setupGlobalErrorHandler() // capture uncaught errors + unhandled rejections
+```
+
+**2. Add the Cloud Function** — in `functions/src/index.ts`:
+
+```ts
+import { initLogger, createClientLogFunction } from '@dasasian/firebase-structured-logger/functions'
+
+initLogger({ appId: 'my-app' })
+
+export const logFrontendEvent = createClientLogFunction({
+  bucketName: 'my-app.firebasestorage.app', // Storage bucket holding source maps
+})
+```
+
+**3. Log** — anywhere in the frontend:
+
+```ts
+logger.info('checkout started', { orderId })
+logger.error(err, { screen: 'camera' }, context, { photo: blob }) // attachments optional
+```
+
+Debug logs are suppressed in production automatically. That's the happy path — the rest of this doc covers source-map symbolication, user context, the CLI, and the local emulator loop.
+
+---
+
+## How it works
+
+```
+Browser  ──logFrontendEvent()──▶  Cloud Function  ──symbolicate──▶  Cloud Logging
+ (client)      httpsCallable          (functions)     (source maps)   (structured)
+```
+
+- The **client** batches structured events and calls your `logFrontendEvent` Cloud Function.
+- The **function** symbolicates any stack trace against source maps in Cloud Storage, then writes a structured entry (in production) or a local JSONL file (in the emulator).
+- You query the result in **Cloud Logging**, or locally from Claude via **[firebase-mcp-server](https://github.com/dasasian/firebase-mcp-server)** (`@dasasian/firebase-mcp-server`).
+
+## Full setup
+
+### Prerequisites
+
+- A `functions/` directory (`firebase init functions`, TypeScript) referenced by `firebase.json`.
+- **Firebase Storage enabled** (source maps are uploaded there): Firebase console → **Storage → Get started**.
+- A frontend build that emits source maps. The `fsl` source-map tooling assumes **Vite**.
+
+### 1. `.gitignore`
+
+```
+functions/logs/*.jsonl
+```
+
+The `logs/` directory holds local JSONL from the emulator — track the directory, not the files:
+
+```bash
+mkdir -p functions/logs && touch functions/logs/.gitkeep
+```
+
+### 2. 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 — keep 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"
+```
+
+`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.
+
+> **`VITE_RELEASE_ID`** ties a build to its source maps — the client tags every entry with it, and `upload-sourcemaps` stores maps under the matching path. Use the same value in both places (the deploy script above sets it once from the git SHA). Locally it defaults to `'dev'`, and no maps are uploaded — symbolication isn't needed in development.
+
+### 3. Typed labels + user context
+
+```ts
+interface MyAppLabels {
+  organizationId?: string
+  itemId?: string
+  // whatever domain entities are relevant
+}
+
+export const logger = initLogger<MyAppLabels>({ /* … */ })
+
+logger.setUser(uid, { /* app labels */ }) // on sign in
+logger.clearUser()                        // on sign out
+logger.setScreen('checkout')              // on navigation
+```
+
+### 4. Run the emulator (local capture)
+
+Add a `serve` script to `functions/package.json`:
+
+```json
+"serve": "npm run build && firebase emulators:start --only functions"
+```
+
+The emulator writes entries to `DEV_LOG_DIR` (e.g. `functions/logs/dev.jsonl`), so you can inspect logs without deploying — and point **[firebase-mcp-server](https://github.com/dasasian/firebase-mcp-server)** at that same file to query your dev logs from Claude.
+
+## Client API
+
+```ts
+logger.error(error, labels?, context?, attachments?)   // attachments: Record<string, Blob | File | string>
+logger.info(message, labels?, context?, attachments?)
+logger.warning(message, labels?, context?, attachments?)
+logger.debug(message, labels?, context?, attachments?) // suppressed in production
+
+logger.setUser(uid, extraLabels?)
+logger.clearUser()
+logger.setScreen(screen)
+logger.addBreadcrumb(type, name, data?)
+```
+
+**Attachments** (images, snapshots, captured data) upload to GCS at `logAttachments/{logId}/{name}`; the same `logId` is on the entry's `labels.logId`. Add a lifecycle rule to auto-delete `logAttachments/` after N days.
+
+## Functions API
+
+```ts
+import { initLogger, initRequestLogger, logError, logInfo } from '@dasasian/firebase-structured-logger/functions'
+
+initLogger({ appId: 'my-app' }) // at module load
+
+export const myFunction = onCall(async (request) => {
+  initRequestLogger(request, { functionName: 'myFunction' }) // seeds userId + functionName
+  logInfo('started')
+})
+```
+
+Backend log methods also accept an optional `attachments` (`Record<string, string | Buffer>`).
+
+## CLI (`fsl`)
+
+```bash
+# Upload source maps to Cloud Storage and strip local .map files (run in deploy)
+npx fsl upload-sourcemaps [--bucket=<name>] [--functions=<path>] [--embed-sourcemaps] [--release=<id>]
+
+# Install the Claude Code skills into the current project (or --global, --force)
+npx fsl install-skills
+```
+
+> The `fsl pack` / `pack-restore` commands exist only for consuming this package via a local `file:` dependency (they vendor a tgz so `firebase deploy` can bundle it). When you install from npm — as above — you don't need them.
+
+## Skills
+
+```bash
+npx fsl install-skills
+```
+
+| Skill | Description |
+|-------|-------------|
+| `/logs` | Validate logging in a file — error paths, labels, PII, missing `initRequestLogger`, breadcrumbs |
+| `/query-logs` | Query Cloud Logging or local JSONL via [firebase-mcp-server](https://github.com/dasasian/firebase-mcp-server) |
+
+## Local log rotation
+
+Logs write to `{logLocalDir}/dev.jsonl`; each emulator start rotates the current file to `dev-{timestamp}.jsonl`, and rotation also happens when the record limit is hit mid-session.
+
+| Config | Default | Description |
+|---|---|---|
+| `logLocalDir` | — | Directory for local log files |
+| `logMaxRecordsPerFile` | 2000 | Records per file before rotation |
+| `logMaxRotatedFiles` | 5 | Rotated files to keep |
+
+## Source maps
+
+For symbolicated production traces, emit source maps in Vite and upload them at deploy:
+
+```ts
+// vite.config.ts
+build: {
+  sourcemap: true,
+  commonjsOptions: {
+    // Rollup's commonjs plugin doesn't cover file: deps by default
+    include: [/firebase-structured-logger/, /node_modules/],
+  },
+}
+```
+
+Maps are stored at `gs://<bucket>/sourcemaps/{releaseId}/{filename}.map` and loaded by the Cloud Function during symbolication.
+
+## License
+
+MIT © Dasasian

package/dist/client/breadcrumbs.d.ts

@@ -0,0 +1,15 @@
+import type { BreadcrumbEntry } from '../shared/types';
+export declare function setCurrentScreen(screen: string): void;
+export declare function setActiveActivity(activity: string | undefined): void;
+export declare function getCurrentScreen(): string | undefined;
+export declare function getActiveActivity(): string | undefined;
+export declare function addBreadcrumb(type: BreadcrumbEntry['type'], name: string, data?: Record<string, unknown>): void;
+export declare function getLastBreadcrumbs(count: number): BreadcrumbEntry[];
+export declare function clearBreadcrumbs(): void;
+export declare const bc: {
+    action: (name: string, data?: Record<string, unknown>) => void;
+    state: (name: string, data?: Record<string, unknown>) => void;
+    nav: (screen: string) => void;
+    error: (type: string, data?: Record<string, unknown>) => void;
+};
+//# sourceMappingURL=breadcrumbs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.d.ts","sourceRoot":"","sources":["../../src/client/breadcrumbs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAStD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGrD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEpE;AAED,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAED,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CAEtD;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CAUN;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE,CAEnE;AAED,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED,eAAO,MAAM,EAAE;mBACE,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;kBACtC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;kBACpC,MAAM;kBACR,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CACtD,CAAA"}

package/dist/client/breadcrumbs.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bc = void 0;
+exports.setCurrentScreen = setCurrentScreen;
+exports.setActiveActivity = setActiveActivity;
+exports.getCurrentScreen = getCurrentScreen;
+exports.getActiveActivity = getActiveActivity;
+exports.addBreadcrumb = addBreadcrumb;
+exports.getLastBreadcrumbs = getLastBreadcrumbs;
+exports.clearBreadcrumbs = clearBreadcrumbs;
+const MAX_BREADCRUMBS = 50;
+const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes
+let currentScreen;
+let activeActivity;
+let breadcrumbs = [];
+function setCurrentScreen(screen) {
+    currentScreen = screen;
+    addBreadcrumb('nav', `navigate_${screen}`);
+}
+function setActiveActivity(activity) {
+    activeActivity = activity;
+}
+function getCurrentScreen() {
+    return currentScreen;
+}
+function getActiveActivity() {
+    return activeActivity;
+}
+function addBreadcrumb(type, name, data) {
+    const entry = { timestamp: Date.now(), type, name, data };
+    breadcrumbs.push(entry);
+    const cutoff = Date.now() - MAX_AGE_MS;
+    breadcrumbs = breadcrumbs.filter((bc) => bc.timestamp > cutoff);
+    if (breadcrumbs.length > MAX_BREADCRUMBS) {
+        breadcrumbs = breadcrumbs.slice(breadcrumbs.length - MAX_BREADCRUMBS);
+    }
+}
+function getLastBreadcrumbs(count) {
+    return breadcrumbs.slice(Math.max(0, breadcrumbs.length - count));
+}
+function clearBreadcrumbs() {
+    breadcrumbs = [];
+    currentScreen = undefined;
+    activeActivity = undefined;
+}
+exports.bc = {
+    action: (name, data) => addBreadcrumb('action', name, data),
+    state: (name, data) => addBreadcrumb('state', name, data),
+    nav: (screen) => setCurrentScreen(screen),
+    error: (type, data) => addBreadcrumb('error', type, data),
+};
+//# sourceMappingURL=breadcrumbs.js.map

package/dist/client/breadcrumbs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breadcrumbs.js","sourceRoot":"","sources":["../../src/client/breadcrumbs.ts"],"names":[],"mappings":";;;AASA,4CAGC;AAED,8CAEC;AAED,4CAEC;AAED,8CAEC;AAED,sCAcC;AAED,gDAEC;AAED,4CAIC;AAhDD,MAAM,eAAe,GAAG,EAAE,CAAA;AAC1B,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA,CAAC,YAAY;AAE7C,IAAI,aAAiC,CAAA;AACrC,IAAI,cAAkC,CAAA;AACtC,IAAI,WAAW,GAAsB,EAAE,CAAA;AAEvC,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,aAAa,GAAG,MAAM,CAAA;IACtB,aAAa,CAAC,KAAK,EAAE,YAAY,MAAM,EAAE,CAAC,CAAA;AAC5C,CAAC;AAED,SAAgB,iBAAiB,CAAC,QAA4B;IAC5D,cAAc,GAAG,QAAQ,CAAA;AAC3B,CAAC;AAED,SAAgB,gBAAgB;IAC9B,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,SAAgB,iBAAiB;IAC/B,OAAO,cAAc,CAAA;AACvB,CAAC;AAED,SAAgB,aAAa,CAC3B,IAA6B,EAC7B,IAAY,EACZ,IAA8B;IAE9B,MAAM,KAAK,GAAoB,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;IAC1E,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,CAAA;IACtC,WAAW,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,CAAA;IAE/D,IAAI,WAAW,CAAC,MAAM,GAAG,eAAe,EAAE,CAAC;QACzC,WAAW,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,GAAG,eAAe,CAAC,CAAA;IACvE,CAAC;AACH,CAAC;AAED,SAAgB,kBAAkB,CAAC,KAAa;IAC9C,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAA;AACnE,CAAC;AAED,SAAgB,gBAAgB;IAC9B,WAAW,GAAG,EAAE,CAAA;IAChB,aAAa,GAAG,SAAS,CAAA;IACzB,cAAc,GAAG,SAAS,CAAA;AAC5B,CAAC;AAEY,QAAA,EAAE,GAAG;IAChB,MAAM,EAAE,CAAC,IAAY,EAAE,IAA8B,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC;IAC7F,KAAK,EAAG,CAAC,IAAY,EAAE,IAA8B,EAAE,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC;IAC5F,GAAG,EAAK,CAAC,MAAc,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC;IACpD,KAAK,EAAG,CAAC,IAAY,EAAE,IAA8B,EAAE,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC;CAC7F,CAAA"}

package/dist/client/errorHandler.d.ts

@@ -0,0 +1,5 @@
+export declare function setupGlobalErrorHandler(): void;
+export declare function handleReactError(error: Error, errorInfo: {
+    componentStack: string;
+}): void;
+//# sourceMappingURL=errorHandler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../src/client/errorHandler.ts"],"names":[],"mappings":"AAEA,wBAAgB,uBAAuB,IAAI,IAAI,CAU9C;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,GACpC,IAAI,CAMN"}

package/dist/client/errorHandler.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupGlobalErrorHandler = setupGlobalErrorHandler;
+exports.handleReactError = handleReactError;
+const logger_1 = require("./logger");
+function setupGlobalErrorHandler() {
+    window.addEventListener('error', (event) => {
+        console.error('[fsl] Uncaught error:', event.error);
+        (0, logger_1.getClientLogger)().error(event.error, { errorCategory: 'crash', errorType: 'UncaughtError' });
+    });
+    window.addEventListener('unhandledrejection', (event) => {
+        console.error('[fsl] Unhandled rejection:', event.reason);
+        (0, logger_1.getClientLogger)().error(event.reason, { errorCategory: 'crash', errorType: 'UnhandledRejection' });
+    });
+}
+function handleReactError(error, errorInfo) {
+    (0, logger_1.getClientLogger)().error(error, { errorCategory: 'crash', errorType: 'ReactError' }, { componentStack: errorInfo.componentStack });
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/client/errorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../src/client/errorHandler.ts"],"names":[],"mappings":";;AAEA,0DAUC;AAED,4CASC;AAvBD,qCAA0C;AAE1C,SAAgB,uBAAuB;IACrC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QACzC,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;QACnD,IAAA,wBAAe,GAAE,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAW,CAAC,CAAA;IACvG,CAAC,CAAC,CAAA;IAEF,MAAM,CAAC,gBAAgB,CAAC,oBAAoB,EAAE,CAAC,KAAK,EAAE,EAAE;QACtD,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;QACzD,IAAA,wBAAe,GAAE,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAW,CAAC,CAAA;IAC7G,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,SAAgB,gBAAgB,CAC9B,KAAY,EACZ,SAAqC;IAErC,IAAA,wBAAe,GAAE,CAAC,KAAK,CACrB,KAAK,EACL,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAW,EAC5D,EAAE,cAAc,EAAE,SAAS,CAAC,cAAc,EAAE,CAC7C,CAAA;AACH,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+export { initLogger, getClientLogger, Logger, triggerTestLog } from './logger';
+export type { InitLoggerConfig, RateLimitConfig } from './logger';
+export { setupGlobalErrorHandler, handleReactError } from './errorHandler';
+export { addBreadcrumb, setActiveActivity, bc } from './breadcrumbs';
+export type { LogSeverity, LogPayload, BreadcrumbEntry, BaseLabels } from '../shared/types';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/client/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bc = exports.setActiveActivity = exports.addBreadcrumb = exports.handleReactError = exports.setupGlobalErrorHandler = exports.triggerTestLog = exports.Logger = 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, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+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; } });
+Object.defineProperty(exports, "handleReactError", { enumerable: true, get: function () { return errorHandler_1.handleReactError; } });
+var breadcrumbs_1 = require("./breadcrumbs");
+Object.defineProperty(exports, "addBreadcrumb", { enumerable: true, get: function () { return breadcrumbs_1.addBreadcrumb; } });
+Object.defineProperty(exports, "setActiveActivity", { enumerable: true, get: function () { return breadcrumbs_1.setActiveActivity; } });
+Object.defineProperty(exports, "bc", { enumerable: true, get: function () { return breadcrumbs_1.bc; } });
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;AAAA,mCAA8E;AAArE,oGAAA,UAAU,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,wGAAA,cAAc,OAAA;AAE5D,+CAA0E;AAAjE,uHAAA,uBAAuB,OAAA;AAAE,gHAAA,gBAAgB,OAAA;AAClD,6CAAoE;AAA3D,4GAAA,aAAa,OAAA;AAAE,gHAAA,iBAAiB,OAAA;AAAE,iGAAA,EAAE,OAAA"}

package/dist/client/logger.d.ts

@@ -0,0 +1,40 @@
+import type { LogSeverity, LogPayload } from '../shared/types';
+import { type RateLimitConfig } from './rateLimiter';
+export type { RateLimitConfig };
+type LogCallable = (data: LogPayload) => Promise<unknown>;
+export interface InitLoggerConfig<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>> {
+    appId: string;
+    releaseId: string;
+    logFunction: LogCallable;
+    minLogLevel?: LogSeverity;
+    rateLimitOptions?: RateLimitConfig;
+}
+export declare class Logger<AppLabels extends Record<string, string | undefined> = Record<string, string | undefined>> {
+    private readonly config;
+    private readonly minLevel;
+    private userId;
+    private userLabels;
+    constructor(config: InitLoggerConfig<AppLabels>);
+    setUser(uid: string, extraLabels?: Partial<AppLabels>): void;
+    clearUser(): void;
+    setScreen(screen: string): void;
+    addBreadcrumb(type: 'action' | 'state' | 'nav' | 'error', name: string, data?: Record<string, unknown>): void;
+    error(raw: unknown, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): void;
+    info(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): void;
+    warning(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): void;
+    debug(message: string, labels?: Partial<AppLabels>, context?: Record<string, unknown>, attachments?: Record<string, Blob | File | string>): void;
+    private send;
+}
+/**
+ * Trigger 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:
+ * 1. dev.jsonl has entries with labels.errorType === 'fsl-verify'
+ * 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 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>;
+//# sourceMappingURL=logger.d.ts.map

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

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

package/dist/client/logger.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+exports.triggerTestLog = triggerTestLog;
+exports.initLogger = initLogger;
+exports.getClientLogger = getClientLogger;
+const breadcrumbs_1 = require("./breadcrumbs");
+const rateLimiter_1 = require("./rateLimiter");
+const SEVERITY_ORDER = {
+    ERROR: 0,
+    WARNING: 1,
+    INFO: 2,
+    DEBUG: 3,
+};
+function defaultMinLevel() {
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production')
+        return 'WARNING';
+    return 'DEBUG';
+}
+function getPlatform() {
+    if (typeof navigator === 'undefined')
+        return 'unknown';
+    const ua = navigator.userAgent;
+    if (/iPhone|iPad|iPod/.test(ua))
+        return 'ios';
+    if (/Android/.test(ua))
+        return 'android';
+    if (/Mac/.test(ua))
+        return 'macos';
+    if (/Win/.test(ua))
+        return 'windows';
+    if (/Linux/.test(ua))
+        return 'linux';
+    return 'web';
+}
+function getBrowser() {
+    if (typeof navigator === 'undefined')
+        return 'unknown';
+    const ua = navigator.userAgent;
+    if (/Firefox/.test(ua))
+        return 'firefox';
+    if (/Edg/.test(ua))
+        return 'edge';
+    if (/Chrome/.test(ua))
+        return 'chrome';
+    if (/Safari/.test(ua))
+        return 'safari';
+    return 'unknown';
+}
+async function blobToBase64(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => {
+            const result = reader.result;
+            resolve(result.split(',')[1] ?? result);
+        };
+        reader.onerror = reject;
+        reader.readAsDataURL(blob);
+    });
+}
+async function assetToBase64(asset) {
+    if (typeof asset === 'string')
+        return asset;
+    return blobToBase64(asset);
+}
+class Logger {
+    config;
+    minLevel;
+    userId;
+    userLabels = {};
+    constructor(config) {
+        this.config = config;
+        this.minLevel = SEVERITY_ORDER[config.minLogLevel ?? defaultMinLevel()];
+        if (config.rateLimitOptions) {
+            (0, rateLimiter_1.configureRateLimiter)(config.rateLimitOptions);
+        }
+    }
+    setUser(uid, extraLabels) {
+        this.userId = uid;
+        this.userLabels = extraLabels ?? {};
+    }
+    clearUser() {
+        this.userId = undefined;
+        this.userLabels = {};
+        (0, breadcrumbs_1.clearBreadcrumbs)();
+    }
+    setScreen(screen) {
+        (0, breadcrumbs_1.setCurrentScreen)(screen);
+    }
+    addBreadcrumb(type, name, data) {
+        (0, breadcrumbs_1.addBreadcrumb)(type, name, data);
+    }
+    error(raw, labels, context, attachments) {
+        const error = raw instanceof Error ? raw : new Error(String(raw));
+        const screen = (0, breadcrumbs_1.getCurrentScreen)();
+        const activity = (0, breadcrumbs_1.getActiveActivity)();
+        if (!(0, rateLimiter_1.canLogError)(error, screen, activity)) {
+            console.error('[fsl] Error suppressed:', error.message);
+            return;
+        }
+        (0, rateLimiter_1.recordError)(error, screen, activity);
+        const errorLabels = {
+            errorType: error.name || 'UnknownError',
+            ...labels,
+        };
+        void this.send(error.message, 'ERROR', errorLabels, context, attachments, {
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+            cause: error.cause != null ? String(error.cause) : undefined,
+        });
+    }
+    info(message, labels, context, attachments) {
+        void this.send(message, 'INFO', labels, context, attachments);
+    }
+    warning(message, labels, context, attachments) {
+        void this.send(message, 'WARNING', labels, context, attachments);
+    }
+    debug(message, labels, context, attachments) {
+        void this.send(message, 'DEBUG', labels, context, attachments);
+    }
+    async send(message, severity, labels, context, attachments, error) {
+        if (SEVERITY_ORDER[severity] > this.minLevel)
+            return;
+        if (!(0, rateLimiter_1.canLogEvent)()) {
+            console.warn('[fsl] Rate limit exceeded');
+            return;
+        }
+        try {
+            const allLabels = {
+                appId: this.config.appId,
+                releaseId: this.config.releaseId,
+                screen: (0, breadcrumbs_1.getCurrentScreen)(),
+                userId: this.userId,
+                platform: getPlatform(),
+                browser: getBrowser(),
+                ...this.userLabels,
+                ...labels,
+            };
+            let base64Attachments;
+            if (attachments && Object.keys(attachments).length > 0) {
+                base64Attachments = {};
+                for (const [name, attachment] of Object.entries(attachments)) {
+                    base64Attachments[name] = await assetToBase64(attachment);
+                }
+            }
+            const payload = {
+                message,
+                severity,
+                labels: allLabels,
+                jsonPayload: {
+                    breadcrumbs: (0, breadcrumbs_1.getLastBreadcrumbs)(20),
+                    context,
+                    error,
+                },
+                ...(base64Attachments ? { attachments: base64Attachments } : {}),
+            };
+            (0, rateLimiter_1.recordLog)();
+            await this.config.logFunction(payload);
+        }
+        catch (err) {
+            console.error('[fsl] Failed to send log:', err instanceof Error ? err.message : err);
+        }
+    }
+}
+exports.Logger = Logger;
+/**
+ * Trigger 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:
+ * 1. dev.jsonl has entries with labels.errorType === 'fsl-verify'
+ * 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" }]
+ */
+function triggerTestLog() {
+    console.info('[fsl] triggerTestLog called');
+    const logger = getClientLogger();
+    const testError = new Error('[fsl-verify] Test error — logging pipeline check');
+    console.info('[fsl] sending error log...');
+    logger.error(testError, { errorType: 'fsl-verify' }, { test: true });
+    console.info('[fsl] sending warning log...');
+    logger.warning('[fsl-verify] Test warning', { errorType: 'fsl-verify' });
+    console.info('[fsl] sending info log...');
+    logger.info('[fsl-verify] Test info', { errorType: 'fsl-verify' });
+    console.info('[fsl] triggerTestLog scheduled — sends are fire-and-forget; check dev.jsonl in ~1-2s');
+}
+// Module-level singleton
+let instance = null;
+function initLogger(config) {
+    instance = new Logger(config);
+    return instance;
+}
+function getClientLogger() {
+    if (!instance)
+        throw new Error('[fsl] initLogger() not called');
+    return instance;
+}
+//# sourceMappingURL=logger.js.map