@cross-deck/buckets 0.1.2 → 0.2.1

package/README.md

@@ -80,6 +80,39 @@ haven't named yet. Buckets counted them at the database driver, not in your code
 
 ---
 
+## Server *and* browser — install where you read
+
+A collector counts reads **where it runs.** With Firestore, your app often reads
+from **two** places: your **server** (the snippet above) and your users'
+**browsers** — live `onSnapshot` listeners and direct `getDocs`/`getDoc` calls
+that bill straight to your project and *never touch your server*. A server-only
+collector can't see those, the same way `@cross-deck/node` can't see a browser
+event. So Buckets ships a collector for each surface.
+
+**Browser** — swap one import and add one line:
+
+```ts
+import { initBucketsWeb, bucket } from "@cross-deck/buckets/web";
+// was: import { getDocs, onSnapshot } from "firebase/firestore"
+import { getDocs, onSnapshot } from "@cross-deck/buckets/web";
+
+initBucketsWeb({ apiKey: "cd_pk_…" }); // your PUBLISHABLE key — safe in client code
+
+bucket("live-feed", () => onSnapshot(liveQuery, render)); // every fire counted
+```
+
+Each listener fire is counted as the documents it delivers — exactly what Firebase
+bills — labelled and reported up the **same pipe**, so your dashboard shows
+**server and browser reads side by side.** Install one, or both. The promise is
+precise: **Buckets captures every read that flows through a collector** — put one
+on each surface you read from, and you see all of it.
+
+> We learned this the hard way dogfooding on our own dashboard: 94% of our reads
+> were browser-side and a server-only install was blind to them. The browser
+> collector is the fix — and the reason "install where you read" is the whole model.
+
+---
+
 ## What you get
 
 A small, cheap, daily document per app — the **rollup**. This is the entire output,
@@ -349,7 +382,8 @@ reconciles against your provider's invoice instead of drifting from it.
 
 | Datastore | Status |
 |---|---|
-| **Google Cloud Firestore** (firebase-admin) | ✅ Supported |
+| **Firestore — server** (`firebase-admin`) | ✅ Supported |
+| **Firestore — browser** (`firebase` JS SDK) | ✅ Supported — `@cross-deck/buckets/web` |
 | Postgres · DynamoDB · MongoDB | 🔜 Adapter interface is public — contributions welcome |
 
 The trap *pattern* generalises to any driver with interceptable read methods, and

package/dist/index.d.mts

@@ -1,58 +1,5 @@
-/**
- * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
- *
- * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
- * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
- * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
- * wants to self-host can implement `Sink` against anything (Postgres, a file, your
- * own API) without touching the meter.
- */
-interface OpCounts {
-    read?: number;
-    write?: number;
-    delete?: number;
-}
-/**
- * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter
- * produces one of these per UTC day in a flush window (usually exactly one).
- */
-interface BucketsReport {
-    /** UTC day "YYYY-MM-DD". */
-    date: string;
-    /** bucket name → counts. The heart of the report. */
-    byLabel: Record<string, OpCounts>;
-    /** UTC hour "HH" → counts, for the hourly "did my fix land this hour?" view. */
-    byHour?: Record<string, OpCounts>;
-}
-/**
- * A destination for coalesced rollups. `flush` MAY throw on failure — the meter
- * catches it, drops that one window, and never lets it reach your app.
- */
-interface Sink {
-    flush(report: BucketsReport): Promise<void>;
-}
-interface ReportSinkConfig {
-    /** The project's `cd_sk_` secret key. Server-to-server only. */
-    apiKey: string;
-    /** Defaults to https://api.cross-deck.com/v1/buckets/report */
-    endpoint?: string;
-    /** Request timeout (ms); a slow Crossdeck must never stall your flush. */
-    timeoutMs?: number;
-}
-/**
- * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
- * The ingest folds it into the day's maintained doc with `increment`, so many
- * reports a minute coalesce safely. This path does ZERO database reads — it sends
- * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
- * window; the meter guarantees it never reaches your app.
- */
-declare class ReportSink implements Sink {
-    private readonly endpoint;
-    private readonly apiKey;
-    private readonly timeoutMs;
-    constructor(config: ReportSinkConfig);
-    flush(report: BucketsReport): Promise<void>;
-}
+import { S as Sink } from './sink-DjFci4Uz.mjs';
+export { B as BucketsReport, O as OpCounts, R as ReportSink, a as ReportSinkConfig } from './sink-DjFci4Uz.mjs';
 
 type OpType = "read" | "write" | "delete";
 /** Optional read-site hint — the collection touched, derived at the trap from the
@@ -176,4 +123,4 @@ interface InitOptions {
  */
 declare function init(options: InitOptions): void;
 
-export { type BucketsReport, type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpCounts, type OpType, ReportSink, type ReportSinkConfig, type Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };
+export { type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpType, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };

package/dist/index.d.ts

@@ -1,58 +1,5 @@
-/**
- * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
- *
- * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
- * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
- * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
- * wants to self-host can implement `Sink` against anything (Postgres, a file, your
- * own API) without touching the meter.
- */
-interface OpCounts {
-    read?: number;
-    write?: number;
-    delete?: number;
-}
-/**
- * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter
- * produces one of these per UTC day in a flush window (usually exactly one).
- */
-interface BucketsReport {
-    /** UTC day "YYYY-MM-DD". */
-    date: string;
-    /** bucket name → counts. The heart of the report. */
-    byLabel: Record<string, OpCounts>;
-    /** UTC hour "HH" → counts, for the hourly "did my fix land this hour?" view. */
-    byHour?: Record<string, OpCounts>;
-}
-/**
- * A destination for coalesced rollups. `flush` MAY throw on failure — the meter
- * catches it, drops that one window, and never lets it reach your app.
- */
-interface Sink {
-    flush(report: BucketsReport): Promise<void>;
-}
-interface ReportSinkConfig {
-    /** The project's `cd_sk_` secret key. Server-to-server only. */
-    apiKey: string;
-    /** Defaults to https://api.cross-deck.com/v1/buckets/report */
-    endpoint?: string;
-    /** Request timeout (ms); a slow Crossdeck must never stall your flush. */
-    timeoutMs?: number;
-}
-/**
- * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
- * The ingest folds it into the day's maintained doc with `increment`, so many
- * reports a minute coalesce safely. This path does ZERO database reads — it sends
- * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
- * window; the meter guarantees it never reaches your app.
- */
-declare class ReportSink implements Sink {
-    private readonly endpoint;
-    private readonly apiKey;
-    private readonly timeoutMs;
-    constructor(config: ReportSinkConfig);
-    flush(report: BucketsReport): Promise<void>;
-}
+import { S as Sink } from './sink-DjFci4Uz.js';
+export { B as BucketsReport, O as OpCounts, R as ReportSink, a as ReportSinkConfig } from './sink-DjFci4Uz.js';
 
 type OpType = "read" | "write" | "delete";
 /** Optional read-site hint — the collection touched, derived at the trap from the
@@ -176,4 +123,4 @@ interface InitOptions {
  */
 declare function init(options: InitOptions): void;
 
-export { type BucketsReport, type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpCounts, type OpType, ReportSink, type ReportSinkConfig, type Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };
+export { type CostHint, type CostTag, type FirestoreClasses, type InitOptions, type MeterConfig, type OpType, Sink, bucket, currentCostTag, enterCostTag, flush, init, init as initBuckets, installFirestoreMeter, recordDeletes, recordReads, recordWrites, refineCostTag, runWithCostTag };

package/dist/sink-DjFci4Uz.d.mts

@@ -0,0 +1,57 @@
+/**
+ * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
+ *
+ * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
+ * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
+ * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
+ * wants to self-host can implement `Sink` against anything (Postgres, a file, your
+ * own API) without touching the meter.
+ */
+interface OpCounts {
+    read?: number;
+    write?: number;
+    delete?: number;
+}
+/**
+ * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter
+ * produces one of these per UTC day in a flush window (usually exactly one).
+ */
+interface BucketsReport {
+    /** UTC day "YYYY-MM-DD". */
+    date: string;
+    /** bucket name → counts. The heart of the report. */
+    byLabel: Record<string, OpCounts>;
+    /** UTC hour "HH" → counts, for the hourly "did my fix land this hour?" view. */
+    byHour?: Record<string, OpCounts>;
+}
+/**
+ * A destination for coalesced rollups. `flush` MAY throw on failure — the meter
+ * catches it, drops that one window, and never lets it reach your app.
+ */
+interface Sink {
+    flush(report: BucketsReport): Promise<void>;
+}
+interface ReportSinkConfig {
+    /** The project's `cd_sk_` secret key. Server-to-server only. */
+    apiKey: string;
+    /** Defaults to https://api.cross-deck.com/v1/buckets/report */
+    endpoint?: string;
+    /** Request timeout (ms); a slow Crossdeck must never stall your flush. */
+    timeoutMs?: number;
+}
+/**
+ * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
+ * The ingest folds it into the day's maintained doc with `increment`, so many
+ * reports a minute coalesce safely. This path does ZERO database reads — it sends
+ * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
+ * window; the meter guarantees it never reaches your app.
+ */
+declare class ReportSink implements Sink {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor(config: ReportSinkConfig);
+    flush(report: BucketsReport): Promise<void>;
+}
+
+export { type BucketsReport as B, type OpCounts as O, ReportSink as R, type Sink as S, type ReportSinkConfig as a };

package/dist/sink-DjFci4Uz.d.ts

@@ -0,0 +1,57 @@
+/**
+ * sink — where the meter sends a coalesced rollup, and the wire shape it sends.
+ *
+ * Abstracting the sink is what makes Buckets storage-agnostic: the meter never
+ * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's
+ * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that
+ * wants to self-host can implement `Sink` against anything (Postgres, a file, your
+ * own API) without touching the meter.
+ */
+interface OpCounts {
+    read?: number;
+    write?: number;
+    delete?: number;
+}
+/**
+ * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter
+ * produces one of these per UTC day in a flush window (usually exactly one).
+ */
+interface BucketsReport {
+    /** UTC day "YYYY-MM-DD". */
+    date: string;
+    /** bucket name → counts. The heart of the report. */
+    byLabel: Record<string, OpCounts>;
+    /** UTC hour "HH" → counts, for the hourly "did my fix land this hour?" view. */
+    byHour?: Record<string, OpCounts>;
+}
+/**
+ * A destination for coalesced rollups. `flush` MAY throw on failure — the meter
+ * catches it, drops that one window, and never lets it reach your app.
+ */
+interface Sink {
+    flush(report: BucketsReport): Promise<void>;
+}
+interface ReportSinkConfig {
+    /** The project's `cd_sk_` secret key. Server-to-server only. */
+    apiKey: string;
+    /** Defaults to https://api.cross-deck.com/v1/buckets/report */
+    endpoint?: string;
+    /** Request timeout (ms); a slow Crossdeck must never stall your flush. */
+    timeoutMs?: number;
+}
+/**
+ * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.
+ * The ingest folds it into the day's maintained doc with `increment`, so many
+ * reports a minute coalesce safely. This path does ZERO database reads — it sends
+ * a summary, it does not read. Throws on a non-202 so the meter can log/drop the
+ * window; the meter guarantees it never reaches your app.
+ */
+declare class ReportSink implements Sink {
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    constructor(config: ReportSinkConfig);
+    flush(report: BucketsReport): Promise<void>;
+}
+
+export { type BucketsReport as B, type OpCounts as O, ReportSink as R, type Sink as S, type ReportSinkConfig as a };

package/dist/web.d.mts

@@ -0,0 +1,101 @@
+import { S as Sink, B as BucketsReport } from './sink-DjFci4Uz.mjs';
+export { O as OpCounts } from './sink-DjFci4Uz.mjs';
+
+/**
+ * web/meter — the browser read meter. Same contract as the Node meter (count in
+ * memory, flush ~1/min, never throw into the app), adapted to the browser:
+ *
+ *  - no AsyncLocalStorage — labels come from web/context (synchronous),
+ *  - "shutdown" is the tab going hidden/closed, so we also flush on
+ *    visibilitychange→hidden and pagehide (a `fetch(..., {keepalive:true})`
+ *    survives the unload),
+ *  - it talks to a Sink exactly like the Node meter, so the wire shape is
+ *    identical and the same ingest receives both.
+ */
+
+interface WebMeterConfig {
+    sink: Sink;
+    flushIntervalMs?: number;
+    onError?: (e: unknown) => void;
+}
+/** Coalesce the buffer into one report per UTC day and hand each to the Sink. */
+declare function flushWeb(): Promise<void>;
+
+/**
+ * Attribute every read SET UP inside `fn` to the bucket `name`:
+ *
+ *   bucket("pulse-map", () => onSnapshot(liveQuery, render));
+ *   // → that listener's reads all show as "pulse-map", forever
+ */
+declare function bucket<T>(name: string, fn: () => T): T;
+
+declare function getDoc(ref: any, ...rest: any[]): Promise<any>;
+declare function getDocs(query: any, ...rest: any[]): Promise<any>;
+/**
+ * onSnapshot has several overloads — (ref, observer), (ref, onNext, onError,
+ * onComplete), and either of those with a leading SnapshotListenOptions. We find
+ * the next-handler wherever it is (a function or `observer.next`) and wrap it to
+ * count on each fire, leaving every other argument exactly as passed.
+ */
+declare function onSnapshot(ref: any, ...args: any[]): any;
+
+/**
+ * web/sink — reports the browser's coalesced rollup up to Crossdeck's ingest.
+ *
+ * Two differences from the Node sink, both forced by the browser:
+ *  - it authenticates with a PUBLISHABLE key (`cd_pk_`), never a secret — a
+ *    secret key cannot live in client code. (The ingest accepts publishable keys
+ *    for Buckets reports the same way the analytics SDK accepts them for events.)
+ *  - it uses `fetch(..., { keepalive: true })` so a report fired as the tab is
+ *    closing still completes.
+ *
+ * It performs ZERO database operations — it sends a summary, it does not read.
+ */
+
+interface WebReportSinkConfig {
+    /** The project's `cd_pk_` PUBLISHABLE key. */
+    apiKey: string;
+    endpoint?: string;
+}
+declare class WebReportSink implements Sink {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(config: WebReportSinkConfig);
+    flush(report: BucketsReport): Promise<void>;
+}
+
+/**
+ * @cross-deck/buckets/web — the BROWSER collector.
+ *
+ * Most Firebase apps read straight from the browser (live `onSnapshot`
+ * listeners, `getDocs`, `getDoc`) — reads billed to your project that a
+ * server-side collector can never see. This adapter closes that hole.
+ *
+ * Setup (two lines + one import swap):
+ *
+ *   import { initBucketsWeb, bucket } from "@cross-deck/buckets/web";
+ *   import { getDoc, getDocs, onSnapshot } from "@cross-deck/buckets/web"; // was "firebase/firestore"
+ *
+ *   initBucketsWeb({ apiKey: "cd_pk_…" }); // your PUBLISHABLE key
+ *
+ *   bucket("pulse-map", () => onSnapshot(liveQuery, render));
+ *
+ * Every read those wrappers see is counted, labelled, and reported up the same
+ * ingest pipe as the server collector — so the dashboard shows server AND browser
+ * reads side by side.
+ */
+
+interface InitWebOptions {
+    /** The project's `cd_pk_` PUBLISHABLE key (safe in client code). */
+    apiKey: string;
+    /** Override the report endpoint (defaults to Crossdeck's ingest). */
+    endpoint?: string;
+    /** How often to flush coalesced counts (ms). Default 60_000. */
+    flushIntervalMs?: number;
+    /** Notified when a flush fails, so a dropped window is never silent. */
+    onError?: WebMeterConfig["onError"];
+}
+/** Configure the browser collector once, at app start. */
+declare function initBucketsWeb(options: InitWebOptions): void;
+
+export { BucketsReport, type InitWebOptions, Sink, WebReportSink, type WebReportSinkConfig, bucket, flushWeb as flush, getDoc, getDocs, initBucketsWeb, onSnapshot };

package/dist/web.d.ts

@@ -0,0 +1,101 @@
+import { S as Sink, B as BucketsReport } from './sink-DjFci4Uz.js';
+export { O as OpCounts } from './sink-DjFci4Uz.js';
+
+/**
+ * web/meter — the browser read meter. Same contract as the Node meter (count in
+ * memory, flush ~1/min, never throw into the app), adapted to the browser:
+ *
+ *  - no AsyncLocalStorage — labels come from web/context (synchronous),
+ *  - "shutdown" is the tab going hidden/closed, so we also flush on
+ *    visibilitychange→hidden and pagehide (a `fetch(..., {keepalive:true})`
+ *    survives the unload),
+ *  - it talks to a Sink exactly like the Node meter, so the wire shape is
+ *    identical and the same ingest receives both.
+ */
+
+interface WebMeterConfig {
+    sink: Sink;
+    flushIntervalMs?: number;
+    onError?: (e: unknown) => void;
+}
+/** Coalesce the buffer into one report per UTC day and hand each to the Sink. */
+declare function flushWeb(): Promise<void>;
+
+/**
+ * Attribute every read SET UP inside `fn` to the bucket `name`:
+ *
+ *   bucket("pulse-map", () => onSnapshot(liveQuery, render));
+ *   // → that listener's reads all show as "pulse-map", forever
+ */
+declare function bucket<T>(name: string, fn: () => T): T;
+
+declare function getDoc(ref: any, ...rest: any[]): Promise<any>;
+declare function getDocs(query: any, ...rest: any[]): Promise<any>;
+/**
+ * onSnapshot has several overloads — (ref, observer), (ref, onNext, onError,
+ * onComplete), and either of those with a leading SnapshotListenOptions. We find
+ * the next-handler wherever it is (a function or `observer.next`) and wrap it to
+ * count on each fire, leaving every other argument exactly as passed.
+ */
+declare function onSnapshot(ref: any, ...args: any[]): any;
+
+/**
+ * web/sink — reports the browser's coalesced rollup up to Crossdeck's ingest.
+ *
+ * Two differences from the Node sink, both forced by the browser:
+ *  - it authenticates with a PUBLISHABLE key (`cd_pk_`), never a secret — a
+ *    secret key cannot live in client code. (The ingest accepts publishable keys
+ *    for Buckets reports the same way the analytics SDK accepts them for events.)
+ *  - it uses `fetch(..., { keepalive: true })` so a report fired as the tab is
+ *    closing still completes.
+ *
+ * It performs ZERO database operations — it sends a summary, it does not read.
+ */
+
+interface WebReportSinkConfig {
+    /** The project's `cd_pk_` PUBLISHABLE key. */
+    apiKey: string;
+    endpoint?: string;
+}
+declare class WebReportSink implements Sink {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(config: WebReportSinkConfig);
+    flush(report: BucketsReport): Promise<void>;
+}
+
+/**
+ * @cross-deck/buckets/web — the BROWSER collector.
+ *
+ * Most Firebase apps read straight from the browser (live `onSnapshot`
+ * listeners, `getDocs`, `getDoc`) — reads billed to your project that a
+ * server-side collector can never see. This adapter closes that hole.
+ *
+ * Setup (two lines + one import swap):
+ *
+ *   import { initBucketsWeb, bucket } from "@cross-deck/buckets/web";
+ *   import { getDoc, getDocs, onSnapshot } from "@cross-deck/buckets/web"; // was "firebase/firestore"
+ *
+ *   initBucketsWeb({ apiKey: "cd_pk_…" }); // your PUBLISHABLE key
+ *
+ *   bucket("pulse-map", () => onSnapshot(liveQuery, render));
+ *
+ * Every read those wrappers see is counted, labelled, and reported up the same
+ * ingest pipe as the server collector — so the dashboard shows server AND browser
+ * reads side by side.
+ */
+
+interface InitWebOptions {
+    /** The project's `cd_pk_` PUBLISHABLE key (safe in client code). */
+    apiKey: string;
+    /** Override the report endpoint (defaults to Crossdeck's ingest). */
+    endpoint?: string;
+    /** How often to flush coalesced counts (ms). Default 60_000. */
+    flushIntervalMs?: number;
+    /** Notified when a flush fails, so a dropped window is never silent. */
+    onError?: WebMeterConfig["onError"];
+}
+/** Configure the browser collector once, at app start. */
+declare function initBucketsWeb(options: InitWebOptions): void;
+
+export { BucketsReport, type InitWebOptions, Sink, WebReportSink, type WebReportSinkConfig, bucket, flushWeb as flush, getDoc, getDocs, initBucketsWeb, onSnapshot };

package/dist/web.js

@@ -0,0 +1,206 @@
+'use strict';
+
+var firestore = require('firebase/firestore');
+
+// src/web/meter.ts
+var SEP = "";
+var labelBuffer = /* @__PURE__ */ new Map();
+var hourBuffer = /* @__PURE__ */ new Map();
+var sink = null;
+var flushIntervalMs = 6e4;
+var onError = null;
+var timer = null;
+var flushing = false;
+var lifecycleBound = false;
+var MAX_BUFFER_KEYS = 5e3;
+function configureWebMeter(config) {
+  sink = config.sink;
+  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;
+  onError = config.onError ?? null;
+}
+var utcDate = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+var utcHour = () => (/* @__PURE__ */ new Date()).toISOString().slice(11, 13);
+function ensureLoop() {
+  if (timer) return;
+  timer = setInterval(() => void flushWeb(), flushIntervalMs);
+  if (!lifecycleBound && typeof addEventListener === "function") {
+    lifecycleBound = true;
+    addEventListener("visibilitychange", () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") void flushWeb();
+    });
+    addEventListener("pagehide", () => void flushWeb());
+  }
+}
+function recordWeb(op, n, label) {
+  try {
+    if (!Number.isFinite(n) || n <= 0) return;
+    const date = utcDate();
+    const lk = date + SEP + op + SEP + label;
+    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);
+    const hk = date + SEP + op + SEP + utcHour();
+    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);
+    ensureLoop();
+    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flushWeb();
+  } catch {
+  }
+}
+function add(target, key, op, n) {
+  const bag = target[key] ??= {};
+  bag[op] = (bag[op] ?? 0) + n;
+}
+async function flushWeb() {
+  if (flushing) return;
+  if (!sink) {
+    labelBuffer.clear();
+    hourBuffer.clear();
+    return;
+  }
+  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;
+  flushing = true;
+  const labels = new Map(labelBuffer);
+  const hours = new Map(hourBuffer);
+  labelBuffer.clear();
+  hourBuffer.clear();
+  try {
+    const byDate = /* @__PURE__ */ new Map();
+    const reportFor = (date) => {
+      let r = byDate.get(date);
+      if (!r) {
+        r = { date, byLabel: {}, byHour: {} };
+        byDate.set(date, r);
+      }
+      return r;
+    };
+    for (const [k, n] of labels) {
+      const [date, op, label] = k.split(SEP);
+      add(reportFor(date).byLabel, label, op, n);
+    }
+    for (const [k, n] of hours) {
+      const [date, op, hour] = k.split(SEP);
+      add(reportFor(date).byHour, hour, op, n);
+    }
+    for (const report of byDate.values()) {
+      await sink.flush(report);
+    }
+  } catch (e) {
+    onError?.(e);
+  } finally {
+    flushing = false;
+  }
+}
+
+// src/web/sink.ts
+var DEFAULT_ENDPOINT = "https://api.cross-deck.com/v1/buckets/report";
+var WebReportSink = class {
+  endpoint;
+  apiKey;
+  constructor(config) {
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.apiKey = config.apiKey;
+  }
+  async flush(report) {
+    const res = await fetch(this.endpoint, {
+      method: "POST",
+      keepalive: true,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(report)
+    });
+    if (res.status !== 202) {
+      throw new Error(`Buckets web report rejected: HTTP ${res.status}`);
+    }
+  }
+};
+
+// src/web/context.ts
+var current;
+function currentLabel() {
+  return current;
+}
+function bucket(name, fn) {
+  const prev = current;
+  current = name;
+  try {
+    return fn();
+  } finally {
+    current = prev;
+  }
+}
+var rawGetDoc = firestore.getDoc;
+var rawGetDocs = firestore.getDocs;
+var rawOnSnapshot = firestore.onSnapshot;
+function collLabel(ref) {
+  try {
+    const path = typeof ref?.path === "string" && ref.path || (ref?._query?.path?.segments?.join?.("/") ?? "") || "";
+    if (path) {
+      const segs2 = path.split("/").filter(Boolean);
+      const coll = segs2.length % 2 === 0 ? segs2[segs2.length - 2] : segs2[segs2.length - 1];
+      return coll ? `col:${coll}` : "uncategorized";
+    }
+    const segs = ref?._query?.path?.segments;
+    if (Array.isArray(segs) && segs.length) return `col:${segs[segs.length - 1]}`;
+  } catch {
+  }
+  return "uncategorized";
+}
+function meter(label, n) {
+  try {
+    recordWeb("read", n, label);
+  } catch {
+  }
+}
+function countSnap(snap) {
+  try {
+    if (typeof snap?.docChanges === "function") return snap.docChanges().length;
+  } catch {
+  }
+  return 1;
+}
+function getDoc(ref, ...rest) {
+  const label = currentLabel() ?? collLabel(ref);
+  return rawGetDoc(ref, ...rest).then((snap) => {
+    meter(label, 1);
+    return snap;
+  });
+}
+function getDocs(query, ...rest) {
+  const label = currentLabel() ?? collLabel(query);
+  return rawGetDocs(query, ...rest).then((snap) => {
+    meter(label, typeof snap?.size === "number" ? Math.max(snap.size, 1) : 1);
+    return snap;
+  });
+}
+function onSnapshot(ref, ...args) {
+  const label = currentLabel() ?? collLabel(ref);
+  const wrapNext = (fn) => typeof fn === "function" ? (snap) => {
+    meter(label, countSnap(snap));
+    return fn(snap);
+  } : fn;
+  const out = args.slice();
+  let i = 0;
+  if (out[0] && typeof out[0] !== "function" && !("next" in out[0])) i = 1;
+  if (out[i] && typeof out[i] === "object" && "next" in out[i]) {
+    out[i] = { ...out[i], next: wrapNext(out[i].next) };
+  } else if (typeof out[i] === "function") {
+    out[i] = wrapNext(out[i]);
+  }
+  return rawOnSnapshot(ref, ...out);
+}
+
+// src/web/index.ts
+function initBucketsWeb(options) {
+  const sink2 = new WebReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });
+  configureWebMeter({ sink: sink2, flushIntervalMs: options.flushIntervalMs, onError: options.onError });
+}
+
+exports.WebReportSink = WebReportSink;
+exports.bucket = bucket;
+exports.flush = flushWeb;
+exports.getDoc = getDoc;
+exports.getDocs = getDocs;
+exports.initBucketsWeb = initBucketsWeb;
+exports.onSnapshot = onSnapshot;
+//# sourceMappingURL=web.js.map
+//# sourceMappingURL=web.js.map

package/dist/web.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web/meter.ts","../src/web/sink.ts","../src/web/context.ts","../src/web/firestore.ts","../src/web/index.ts"],"names":["_getDoc","_getDocs","_onSnapshot","segs","sink"],"mappings":"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","file":"web.js","sourcesContent":["/**\n * web/meter — the browser read meter. Same contract as the Node meter (count in\n * memory, flush ~1/min, never throw into the app), adapted to the browser:\n *\n *  - no AsyncLocalStorage — labels come from web/context (synchronous),\n *  - \"shutdown\" is the tab going hidden/closed, so we also flush on\n *    visibilitychange→hidden and pagehide (a `fetch(..., {keepalive:true})`\n *    survives the unload),\n *  - it talks to a Sink exactly like the Node meter, so the wire shape is\n *    identical and the same ingest receives both.\n */\nimport type { Sink, BucketsReport, OpCounts } from \"../sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n// ASCII Unit Separator — a bucket/collection name never contains it, so the\n// composite key splits back cleanly.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <US> op <US> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <US> op <US> hour → count */\nconst hourBuffer = new Map<string, number>();\n\nlet sink: Sink | null = null;\nlet flushIntervalMs = 60_000;\nlet onError: ((e: unknown) => void) | null = null;\nlet timer: ReturnType<typeof setInterval> | null = null;\nlet flushing = false;\nlet lifecycleBound = false;\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface WebMeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\nexport function configureWebMeter(config: WebMeterConfig): void {\n  sink = config.sink;\n  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;\n  onError = config.onError ?? null;\n}\n\nconst utcDate = (): string => new Date().toISOString().slice(0, 10);\nconst utcHour = (): string => new Date().toISOString().slice(11, 13);\n\nfunction ensureLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flushWeb(), flushIntervalMs);\n  if (!lifecycleBound && typeof addEventListener === \"function\") {\n    lifecycleBound = true;\n    // The tab being hidden or torn down is the browser's \"shutdown\" — flush the\n    // last window. keepalive on the sink's fetch lets it complete during unload.\n    addEventListener(\"visibilitychange\", () => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"hidden\") void flushWeb();\n    });\n    addEventListener(\"pagehide\", () => void flushWeb());\n  }\n}\n\n/** Count `n` ops of `op` against `label`. Never throws. */\nexport function recordWeb(op: OpType, n: number, label: string): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const date = utcDate();\n    const lk = date + SEP + op + SEP + label;\n    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);\n    const hk = date + SEP + op + SEP + utcHour();\n    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);\n    ensureLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flushWeb();\n  } catch {\n    /* metering is best-effort — never disturb the page */\n  }\n}\n\nfunction add(target: Record<string, OpCounts>, key: string, op: OpType, n: number): void {\n  const bag = (target[key] ??= {});\n  bag[op] = (bag[op] ?? 0) + n;\n}\n\n/** Coalesce the buffer into one report per UTC day and hand each to the Sink. */\nexport async function flushWeb(): Promise<void> {\n  if (flushing) return;\n  if (!sink) {\n    labelBuffer.clear();\n    hourBuffer.clear();\n    return;\n  }\n  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;\n  flushing = true;\n\n  const labels = new Map(labelBuffer);\n  const hours = new Map(hourBuffer);\n  labelBuffer.clear();\n  hourBuffer.clear();\n\n  try {\n    const byDate = new Map<string, BucketsReport>();\n    const reportFor = (date: string): BucketsReport => {\n      let r = byDate.get(date);\n      if (!r) {\n        r = { date, byLabel: {}, byHour: {} };\n        byDate.set(date, r);\n      }\n      return r;\n    };\n    for (const [k, n] of labels) {\n      const [date, op, label] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byLabel, label, op, n);\n    }\n    for (const [k, n] of hours) {\n      const [date, op, hour] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byHour!, hour, op, n);\n    }\n    for (const report of byDate.values()) {\n      await sink.flush(report);\n    }\n  } catch (e) {\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * web/sink — reports the browser's coalesced rollup up to Crossdeck's ingest.\n *\n * Two differences from the Node sink, both forced by the browser:\n *  - it authenticates with a PUBLISHABLE key (`cd_pk_`), never a secret — a\n *    secret key cannot live in client code. (The ingest accepts publishable keys\n *    for Buckets reports the same way the analytics SDK accepts them for events.)\n *  - it uses `fetch(..., { keepalive: true })` so a report fired as the tab is\n *    closing still completes.\n *\n * It performs ZERO database operations — it sends a summary, it does not read.\n */\nimport type { BucketsReport, Sink } from \"../sink\";\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\nexport interface WebReportSinkConfig {\n  /** The project's `cd_pk_` PUBLISHABLE key. */\n  apiKey: string;\n  endpoint?: string;\n}\n\nexport class WebReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n\n  constructor(config: WebReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      keepalive: true,\n      headers: {\n        \"content-type\": \"application/json\",\n        authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify(report),\n    });\n    if (res.status !== 202) {\n      throw new Error(`Buckets web report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * web/context — the browser's tagging primitive.\n *\n * The Node collector rides AsyncLocalStorage to attribute reads to a bucket\n * across async fan-outs. The browser has no AsyncLocalStorage — but it doesn't\n * need one: a read (a `getDocs` call, an `onSnapshot` registration) is set up\n * SYNCHRONOUSLY, so a plain module-level \"current label\" captured at call time is\n * exact. `bucket(name, fn)` sets it for the synchronous body of `fn` and restores\n * it after — so the read inside picks up the name, and an `onSnapshot` listener\n * keeps that name for every future fire.\n */\n\nlet current: string | undefined;\n\n/** The bucket name in effect right now, or undefined (→ cascade to collection). */\nexport function currentLabel(): string | undefined {\n  return current;\n}\n\n/**\n * Attribute every read SET UP inside `fn` to the bucket `name`:\n *\n *   bucket(\"pulse-map\", () => onSnapshot(liveQuery, render));\n *   // → that listener's reads all show as \"pulse-map\", forever\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  const prev = current;\n  current = name;\n  try {\n    return fn();\n  } finally {\n    current = prev;\n  }\n}\n","/**\n * web/firestore — drop-in wrappers for the three Firestore client read calls.\n *\n * Swap your import source and nothing else:\n *   - import { getDoc, getDocs, onSnapshot } from \"firebase/firestore\"\n *   + import { getDoc, getDocs, onSnapshot } from \"@cross-deck/buckets/web\"\n *\n * Each wrapper calls the REAL Firestore function, counts the documents it\n * delivers (exactly what Firestore bills), labels it (your `bucket()` name, else\n * the collection), and returns the real result untouched. It can never change a\n * result or throw from the metering — same safety contract as the server trap.\n *\n * COUNTING:\n *   - getDoc        → 1 read\n *   - getDocs       → snapshot.size reads\n *   - onSnapshot    → on EVERY fire, the number of doc changes delivered\n *     (first fire = all matching docs; each update = just the changed ones —\n *     which is precisely what a listener is billed).\n */\nimport {\n  getDoc as _getDoc,\n  getDocs as _getDocs,\n  onSnapshot as _onSnapshot,\n} from \"firebase/firestore\";\nimport { recordWeb } from \"./meter\";\nimport { currentLabel } from \"./context\";\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n// The real Firestore reads have many typed overloads; we pass arguments through\n// verbatim, so call them through loose aliases (the wrappers preserve behaviour).\nconst rawGetDoc = _getDoc as (...args: any[]) => Promise<any>;\nconst rawGetDocs = _getDocs as (...args: any[]) => Promise<any>;\nconst rawOnSnapshot = _onSnapshot as (...args: any[]) => any;\n\n/** Best-effort collection label from a ref/query. PURE; never throws. */\nfunction collLabel(ref: any): string {\n  try {\n    const path: string =\n      (typeof ref?.path === \"string\" && ref.path) ||\n      (ref?._query?.path?.segments?.join?.(\"/\") ?? \"\") ||\n      \"\";\n    if (path) {\n      const segs = path.split(\"/\").filter(Boolean);\n      // even segment count → document path (…/coll/id); odd → collection.\n      const coll = segs.length % 2 === 0 ? segs[segs.length - 2] : segs[segs.length - 1];\n      return coll ? `col:${coll}` : \"uncategorized\";\n    }\n    const segs = ref?._query?.path?.segments;\n    if (Array.isArray(segs) && segs.length) return `col:${segs[segs.length - 1]}`;\n  } catch {\n    /* never throw from labelling */\n  }\n  return \"uncategorized\";\n}\n\nfunction meter(label: string, n: number): void {\n  try {\n    recordWeb(\"read\", n, label);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/** Count the docs a snapshot delivers: a query's changed docs, or 1 for a doc. */\nfunction countSnap(snap: any): number {\n  try {\n    if (typeof snap?.docChanges === \"function\") return snap.docChanges().length;\n  } catch {\n    /* fall through */\n  }\n  return 1;\n}\n\nexport function getDoc(ref: any, ...rest: any[]): Promise<any> {\n  const label = currentLabel() ?? collLabel(ref);\n  return rawGetDoc(ref, ...rest).then((snap: any) => {\n    meter(label, 1);\n    return snap;\n  });\n}\n\nexport function getDocs(query: any, ...rest: any[]): Promise<any> {\n  const label = currentLabel() ?? collLabel(query);\n  return rawGetDocs(query, ...rest).then((snap: any) => {\n    meter(label, typeof snap?.size === \"number\" ? Math.max(snap.size, 1) : 1);\n    return snap;\n  });\n}\n\n/**\n * onSnapshot has several overloads — (ref, observer), (ref, onNext, onError,\n * onComplete), and either of those with a leading SnapshotListenOptions. We find\n * the next-handler wherever it is (a function or `observer.next`) and wrap it to\n * count on each fire, leaving every other argument exactly as passed.\n */\nexport function onSnapshot(ref: any, ...args: any[]): any {\n  const label = currentLabel() ?? collLabel(ref);\n  const wrapNext = (fn: any) =>\n    typeof fn === \"function\"\n      ? (snap: any) => {\n          meter(label, countSnap(snap));\n          return fn(snap);\n        }\n      : fn;\n\n  const out = args.slice();\n  // Leading options object (not a function, not an observer): skip it.\n  let i = 0;\n  if (out[0] && typeof out[0] !== \"function\" && !(\"next\" in out[0])) i = 1;\n\n  if (out[i] && typeof out[i] === \"object\" && \"next\" in out[i]) {\n    // observer form: clone with wrapped next\n    out[i] = { ...out[i], next: wrapNext(out[i].next) };\n  } else if (typeof out[i] === \"function\") {\n    // callback form: wrap onNext (the first function)\n    out[i] = wrapNext(out[i]);\n  }\n\n  return rawOnSnapshot(ref, ...out);\n}\n","/**\n * @cross-deck/buckets/web — the BROWSER collector.\n *\n * Most Firebase apps read straight from the browser (live `onSnapshot`\n * listeners, `getDocs`, `getDoc`) — reads billed to your project that a\n * server-side collector can never see. This adapter closes that hole.\n *\n * Setup (two lines + one import swap):\n *\n *   import { initBucketsWeb, bucket } from \"@cross-deck/buckets/web\";\n *   import { getDoc, getDocs, onSnapshot } from \"@cross-deck/buckets/web\"; // was \"firebase/firestore\"\n *\n *   initBucketsWeb({ apiKey: \"cd_pk_…\" }); // your PUBLISHABLE key\n *\n *   bucket(\"pulse-map\", () => onSnapshot(liveQuery, render));\n *\n * Every read those wrappers see is counted, labelled, and reported up the same\n * ingest pipe as the server collector — so the dashboard shows server AND browser\n * reads side by side.\n */\nimport { configureWebMeter, flushWeb, type WebMeterConfig } from \"./meter\";\nimport { WebReportSink } from \"./sink\";\n\nexport interface InitWebOptions {\n  /** The project's `cd_pk_` PUBLISHABLE key (safe in client code). */\n  apiKey: string;\n  /** Override the report endpoint (defaults to Crossdeck's ingest). */\n  endpoint?: string;\n  /** How often to flush coalesced counts (ms). Default 60_000. */\n  flushIntervalMs?: number;\n  /** Notified when a flush fails, so a dropped window is never silent. */\n  onError?: WebMeterConfig[\"onError\"];\n}\n\n/** Configure the browser collector once, at app start. */\nexport function initBucketsWeb(options: InitWebOptions): void {\n  const sink = new WebReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureWebMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n}\n\n// The tagging verb + the metered read wrappers.\nexport { bucket } from \"./context\";\nexport { getDoc, getDocs, onSnapshot } from \"./firestore\";\nexport { flushWeb as flush } from \"./meter\";\n\n// The sink seam — for self-hosting the browser rollups instead of reporting to Crossdeck.\nexport { WebReportSink, type WebReportSinkConfig } from \"./sink\";\nexport type { BucketsReport, OpCounts, Sink } from \"../sink\";\n"]}

package/dist/web.mjs

@@ -0,0 +1,198 @@
+import { getDoc as getDoc$1, getDocs as getDocs$1, onSnapshot as onSnapshot$1 } from 'firebase/firestore';
+
+// src/web/meter.ts
+var SEP = "";
+var labelBuffer = /* @__PURE__ */ new Map();
+var hourBuffer = /* @__PURE__ */ new Map();
+var sink = null;
+var flushIntervalMs = 6e4;
+var onError = null;
+var timer = null;
+var flushing = false;
+var lifecycleBound = false;
+var MAX_BUFFER_KEYS = 5e3;
+function configureWebMeter(config) {
+  sink = config.sink;
+  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;
+  onError = config.onError ?? null;
+}
+var utcDate = () => (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+var utcHour = () => (/* @__PURE__ */ new Date()).toISOString().slice(11, 13);
+function ensureLoop() {
+  if (timer) return;
+  timer = setInterval(() => void flushWeb(), flushIntervalMs);
+  if (!lifecycleBound && typeof addEventListener === "function") {
+    lifecycleBound = true;
+    addEventListener("visibilitychange", () => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") void flushWeb();
+    });
+    addEventListener("pagehide", () => void flushWeb());
+  }
+}
+function recordWeb(op, n, label) {
+  try {
+    if (!Number.isFinite(n) || n <= 0) return;
+    const date = utcDate();
+    const lk = date + SEP + op + SEP + label;
+    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);
+    const hk = date + SEP + op + SEP + utcHour();
+    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);
+    ensureLoop();
+    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flushWeb();
+  } catch {
+  }
+}
+function add(target, key, op, n) {
+  const bag = target[key] ??= {};
+  bag[op] = (bag[op] ?? 0) + n;
+}
+async function flushWeb() {
+  if (flushing) return;
+  if (!sink) {
+    labelBuffer.clear();
+    hourBuffer.clear();
+    return;
+  }
+  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;
+  flushing = true;
+  const labels = new Map(labelBuffer);
+  const hours = new Map(hourBuffer);
+  labelBuffer.clear();
+  hourBuffer.clear();
+  try {
+    const byDate = /* @__PURE__ */ new Map();
+    const reportFor = (date) => {
+      let r = byDate.get(date);
+      if (!r) {
+        r = { date, byLabel: {}, byHour: {} };
+        byDate.set(date, r);
+      }
+      return r;
+    };
+    for (const [k, n] of labels) {
+      const [date, op, label] = k.split(SEP);
+      add(reportFor(date).byLabel, label, op, n);
+    }
+    for (const [k, n] of hours) {
+      const [date, op, hour] = k.split(SEP);
+      add(reportFor(date).byHour, hour, op, n);
+    }
+    for (const report of byDate.values()) {
+      await sink.flush(report);
+    }
+  } catch (e) {
+    onError?.(e);
+  } finally {
+    flushing = false;
+  }
+}
+
+// src/web/sink.ts
+var DEFAULT_ENDPOINT = "https://api.cross-deck.com/v1/buckets/report";
+var WebReportSink = class {
+  endpoint;
+  apiKey;
+  constructor(config) {
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.apiKey = config.apiKey;
+  }
+  async flush(report) {
+    const res = await fetch(this.endpoint, {
+      method: "POST",
+      keepalive: true,
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify(report)
+    });
+    if (res.status !== 202) {
+      throw new Error(`Buckets web report rejected: HTTP ${res.status}`);
+    }
+  }
+};
+
+// src/web/context.ts
+var current;
+function currentLabel() {
+  return current;
+}
+function bucket(name, fn) {
+  const prev = current;
+  current = name;
+  try {
+    return fn();
+  } finally {
+    current = prev;
+  }
+}
+var rawGetDoc = getDoc$1;
+var rawGetDocs = getDocs$1;
+var rawOnSnapshot = onSnapshot$1;
+function collLabel(ref) {
+  try {
+    const path = typeof ref?.path === "string" && ref.path || (ref?._query?.path?.segments?.join?.("/") ?? "") || "";
+    if (path) {
+      const segs2 = path.split("/").filter(Boolean);
+      const coll = segs2.length % 2 === 0 ? segs2[segs2.length - 2] : segs2[segs2.length - 1];
+      return coll ? `col:${coll}` : "uncategorized";
+    }
+    const segs = ref?._query?.path?.segments;
+    if (Array.isArray(segs) && segs.length) return `col:${segs[segs.length - 1]}`;
+  } catch {
+  }
+  return "uncategorized";
+}
+function meter(label, n) {
+  try {
+    recordWeb("read", n, label);
+  } catch {
+  }
+}
+function countSnap(snap) {
+  try {
+    if (typeof snap?.docChanges === "function") return snap.docChanges().length;
+  } catch {
+  }
+  return 1;
+}
+function getDoc(ref, ...rest) {
+  const label = currentLabel() ?? collLabel(ref);
+  return rawGetDoc(ref, ...rest).then((snap) => {
+    meter(label, 1);
+    return snap;
+  });
+}
+function getDocs(query, ...rest) {
+  const label = currentLabel() ?? collLabel(query);
+  return rawGetDocs(query, ...rest).then((snap) => {
+    meter(label, typeof snap?.size === "number" ? Math.max(snap.size, 1) : 1);
+    return snap;
+  });
+}
+function onSnapshot(ref, ...args) {
+  const label = currentLabel() ?? collLabel(ref);
+  const wrapNext = (fn) => typeof fn === "function" ? (snap) => {
+    meter(label, countSnap(snap));
+    return fn(snap);
+  } : fn;
+  const out = args.slice();
+  let i = 0;
+  if (out[0] && typeof out[0] !== "function" && !("next" in out[0])) i = 1;
+  if (out[i] && typeof out[i] === "object" && "next" in out[i]) {
+    out[i] = { ...out[i], next: wrapNext(out[i].next) };
+  } else if (typeof out[i] === "function") {
+    out[i] = wrapNext(out[i]);
+  }
+  return rawOnSnapshot(ref, ...out);
+}
+
+// src/web/index.ts
+function initBucketsWeb(options) {
+  const sink2 = new WebReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });
+  configureWebMeter({ sink: sink2, flushIntervalMs: options.flushIntervalMs, onError: options.onError });
+}
+
+export { WebReportSink, bucket, flushWeb as flush, getDoc, getDocs, initBucketsWeb, onSnapshot };
+//# sourceMappingURL=web.mjs.map
+//# sourceMappingURL=web.mjs.map

package/dist/web.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/web/meter.ts","../src/web/sink.ts","../src/web/context.ts","../src/web/firestore.ts","../src/web/index.ts"],"names":["_getDoc","_getDocs","_onSnapshot","segs","sink"],"mappings":"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","file":"web.mjs","sourcesContent":["/**\n * web/meter — the browser read meter. Same contract as the Node meter (count in\n * memory, flush ~1/min, never throw into the app), adapted to the browser:\n *\n *  - no AsyncLocalStorage — labels come from web/context (synchronous),\n *  - \"shutdown\" is the tab going hidden/closed, so we also flush on\n *    visibilitychange→hidden and pagehide (a `fetch(..., {keepalive:true})`\n *    survives the unload),\n *  - it talks to a Sink exactly like the Node meter, so the wire shape is\n *    identical and the same ingest receives both.\n */\nimport type { Sink, BucketsReport, OpCounts } from \"../sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n// ASCII Unit Separator — a bucket/collection name never contains it, so the\n// composite key splits back cleanly.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <US> op <US> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <US> op <US> hour → count */\nconst hourBuffer = new Map<string, number>();\n\nlet sink: Sink | null = null;\nlet flushIntervalMs = 60_000;\nlet onError: ((e: unknown) => void) | null = null;\nlet timer: ReturnType<typeof setInterval> | null = null;\nlet flushing = false;\nlet lifecycleBound = false;\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface WebMeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\nexport function configureWebMeter(config: WebMeterConfig): void {\n  sink = config.sink;\n  if (config.flushIntervalMs && config.flushIntervalMs > 0) flushIntervalMs = config.flushIntervalMs;\n  onError = config.onError ?? null;\n}\n\nconst utcDate = (): string => new Date().toISOString().slice(0, 10);\nconst utcHour = (): string => new Date().toISOString().slice(11, 13);\n\nfunction ensureLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flushWeb(), flushIntervalMs);\n  if (!lifecycleBound && typeof addEventListener === \"function\") {\n    lifecycleBound = true;\n    // The tab being hidden or torn down is the browser's \"shutdown\" — flush the\n    // last window. keepalive on the sink's fetch lets it complete during unload.\n    addEventListener(\"visibilitychange\", () => {\n      if (typeof document !== \"undefined\" && document.visibilityState === \"hidden\") void flushWeb();\n    });\n    addEventListener(\"pagehide\", () => void flushWeb());\n  }\n}\n\n/** Count `n` ops of `op` against `label`. Never throws. */\nexport function recordWeb(op: OpType, n: number, label: string): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const date = utcDate();\n    const lk = date + SEP + op + SEP + label;\n    labelBuffer.set(lk, (labelBuffer.get(lk) ?? 0) + n);\n    const hk = date + SEP + op + SEP + utcHour();\n    hourBuffer.set(hk, (hourBuffer.get(hk) ?? 0) + n);\n    ensureLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flushWeb();\n  } catch {\n    /* metering is best-effort — never disturb the page */\n  }\n}\n\nfunction add(target: Record<string, OpCounts>, key: string, op: OpType, n: number): void {\n  const bag = (target[key] ??= {});\n  bag[op] = (bag[op] ?? 0) + n;\n}\n\n/** Coalesce the buffer into one report per UTC day and hand each to the Sink. */\nexport async function flushWeb(): Promise<void> {\n  if (flushing) return;\n  if (!sink) {\n    labelBuffer.clear();\n    hourBuffer.clear();\n    return;\n  }\n  if (labelBuffer.size === 0 && hourBuffer.size === 0) return;\n  flushing = true;\n\n  const labels = new Map(labelBuffer);\n  const hours = new Map(hourBuffer);\n  labelBuffer.clear();\n  hourBuffer.clear();\n\n  try {\n    const byDate = new Map<string, BucketsReport>();\n    const reportFor = (date: string): BucketsReport => {\n      let r = byDate.get(date);\n      if (!r) {\n        r = { date, byLabel: {}, byHour: {} };\n        byDate.set(date, r);\n      }\n      return r;\n    };\n    for (const [k, n] of labels) {\n      const [date, op, label] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byLabel, label, op, n);\n    }\n    for (const [k, n] of hours) {\n      const [date, op, hour] = k.split(SEP) as [string, OpType, string];\n      add(reportFor(date).byHour!, hour, op, n);\n    }\n    for (const report of byDate.values()) {\n      await sink.flush(report);\n    }\n  } catch (e) {\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * web/sink — reports the browser's coalesced rollup up to Crossdeck's ingest.\n *\n * Two differences from the Node sink, both forced by the browser:\n *  - it authenticates with a PUBLISHABLE key (`cd_pk_`), never a secret — a\n *    secret key cannot live in client code. (The ingest accepts publishable keys\n *    for Buckets reports the same way the analytics SDK accepts them for events.)\n *  - it uses `fetch(..., { keepalive: true })` so a report fired as the tab is\n *    closing still completes.\n *\n * It performs ZERO database operations — it sends a summary, it does not read.\n */\nimport type { BucketsReport, Sink } from \"../sink\";\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\nexport interface WebReportSinkConfig {\n  /** The project's `cd_pk_` PUBLISHABLE key. */\n  apiKey: string;\n  endpoint?: string;\n}\n\nexport class WebReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n\n  constructor(config: WebReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      keepalive: true,\n      headers: {\n        \"content-type\": \"application/json\",\n        authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify(report),\n    });\n    if (res.status !== 202) {\n      throw new Error(`Buckets web report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * web/context — the browser's tagging primitive.\n *\n * The Node collector rides AsyncLocalStorage to attribute reads to a bucket\n * across async fan-outs. The browser has no AsyncLocalStorage — but it doesn't\n * need one: a read (a `getDocs` call, an `onSnapshot` registration) is set up\n * SYNCHRONOUSLY, so a plain module-level \"current label\" captured at call time is\n * exact. `bucket(name, fn)` sets it for the synchronous body of `fn` and restores\n * it after — so the read inside picks up the name, and an `onSnapshot` listener\n * keeps that name for every future fire.\n */\n\nlet current: string | undefined;\n\n/** The bucket name in effect right now, or undefined (→ cascade to collection). */\nexport function currentLabel(): string | undefined {\n  return current;\n}\n\n/**\n * Attribute every read SET UP inside `fn` to the bucket `name`:\n *\n *   bucket(\"pulse-map\", () => onSnapshot(liveQuery, render));\n *   // → that listener's reads all show as \"pulse-map\", forever\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  const prev = current;\n  current = name;\n  try {\n    return fn();\n  } finally {\n    current = prev;\n  }\n}\n","/**\n * web/firestore — drop-in wrappers for the three Firestore client read calls.\n *\n * Swap your import source and nothing else:\n *   - import { getDoc, getDocs, onSnapshot } from \"firebase/firestore\"\n *   + import { getDoc, getDocs, onSnapshot } from \"@cross-deck/buckets/web\"\n *\n * Each wrapper calls the REAL Firestore function, counts the documents it\n * delivers (exactly what Firestore bills), labels it (your `bucket()` name, else\n * the collection), and returns the real result untouched. It can never change a\n * result or throw from the metering — same safety contract as the server trap.\n *\n * COUNTING:\n *   - getDoc        → 1 read\n *   - getDocs       → snapshot.size reads\n *   - onSnapshot    → on EVERY fire, the number of doc changes delivered\n *     (first fire = all matching docs; each update = just the changed ones —\n *     which is precisely what a listener is billed).\n */\nimport {\n  getDoc as _getDoc,\n  getDocs as _getDocs,\n  onSnapshot as _onSnapshot,\n} from \"firebase/firestore\";\nimport { recordWeb } from \"./meter\";\nimport { currentLabel } from \"./context\";\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\n\n// The real Firestore reads have many typed overloads; we pass arguments through\n// verbatim, so call them through loose aliases (the wrappers preserve behaviour).\nconst rawGetDoc = _getDoc as (...args: any[]) => Promise<any>;\nconst rawGetDocs = _getDocs as (...args: any[]) => Promise<any>;\nconst rawOnSnapshot = _onSnapshot as (...args: any[]) => any;\n\n/** Best-effort collection label from a ref/query. PURE; never throws. */\nfunction collLabel(ref: any): string {\n  try {\n    const path: string =\n      (typeof ref?.path === \"string\" && ref.path) ||\n      (ref?._query?.path?.segments?.join?.(\"/\") ?? \"\") ||\n      \"\";\n    if (path) {\n      const segs = path.split(\"/\").filter(Boolean);\n      // even segment count → document path (…/coll/id); odd → collection.\n      const coll = segs.length % 2 === 0 ? segs[segs.length - 2] : segs[segs.length - 1];\n      return coll ? `col:${coll}` : \"uncategorized\";\n    }\n    const segs = ref?._query?.path?.segments;\n    if (Array.isArray(segs) && segs.length) return `col:${segs[segs.length - 1]}`;\n  } catch {\n    /* never throw from labelling */\n  }\n  return \"uncategorized\";\n}\n\nfunction meter(label: string, n: number): void {\n  try {\n    recordWeb(\"read\", n, label);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/** Count the docs a snapshot delivers: a query's changed docs, or 1 for a doc. */\nfunction countSnap(snap: any): number {\n  try {\n    if (typeof snap?.docChanges === \"function\") return snap.docChanges().length;\n  } catch {\n    /* fall through */\n  }\n  return 1;\n}\n\nexport function getDoc(ref: any, ...rest: any[]): Promise<any> {\n  const label = currentLabel() ?? collLabel(ref);\n  return rawGetDoc(ref, ...rest).then((snap: any) => {\n    meter(label, 1);\n    return snap;\n  });\n}\n\nexport function getDocs(query: any, ...rest: any[]): Promise<any> {\n  const label = currentLabel() ?? collLabel(query);\n  return rawGetDocs(query, ...rest).then((snap: any) => {\n    meter(label, typeof snap?.size === \"number\" ? Math.max(snap.size, 1) : 1);\n    return snap;\n  });\n}\n\n/**\n * onSnapshot has several overloads — (ref, observer), (ref, onNext, onError,\n * onComplete), and either of those with a leading SnapshotListenOptions. We find\n * the next-handler wherever it is (a function or `observer.next`) and wrap it to\n * count on each fire, leaving every other argument exactly as passed.\n */\nexport function onSnapshot(ref: any, ...args: any[]): any {\n  const label = currentLabel() ?? collLabel(ref);\n  const wrapNext = (fn: any) =>\n    typeof fn === \"function\"\n      ? (snap: any) => {\n          meter(label, countSnap(snap));\n          return fn(snap);\n        }\n      : fn;\n\n  const out = args.slice();\n  // Leading options object (not a function, not an observer): skip it.\n  let i = 0;\n  if (out[0] && typeof out[0] !== \"function\" && !(\"next\" in out[0])) i = 1;\n\n  if (out[i] && typeof out[i] === \"object\" && \"next\" in out[i]) {\n    // observer form: clone with wrapped next\n    out[i] = { ...out[i], next: wrapNext(out[i].next) };\n  } else if (typeof out[i] === \"function\") {\n    // callback form: wrap onNext (the first function)\n    out[i] = wrapNext(out[i]);\n  }\n\n  return rawOnSnapshot(ref, ...out);\n}\n","/**\n * @cross-deck/buckets/web — the BROWSER collector.\n *\n * Most Firebase apps read straight from the browser (live `onSnapshot`\n * listeners, `getDocs`, `getDoc`) — reads billed to your project that a\n * server-side collector can never see. This adapter closes that hole.\n *\n * Setup (two lines + one import swap):\n *\n *   import { initBucketsWeb, bucket } from \"@cross-deck/buckets/web\";\n *   import { getDoc, getDocs, onSnapshot } from \"@cross-deck/buckets/web\"; // was \"firebase/firestore\"\n *\n *   initBucketsWeb({ apiKey: \"cd_pk_…\" }); // your PUBLISHABLE key\n *\n *   bucket(\"pulse-map\", () => onSnapshot(liveQuery, render));\n *\n * Every read those wrappers see is counted, labelled, and reported up the same\n * ingest pipe as the server collector — so the dashboard shows server AND browser\n * reads side by side.\n */\nimport { configureWebMeter, flushWeb, type WebMeterConfig } from \"./meter\";\nimport { WebReportSink } from \"./sink\";\n\nexport interface InitWebOptions {\n  /** The project's `cd_pk_` PUBLISHABLE key (safe in client code). */\n  apiKey: string;\n  /** Override the report endpoint (defaults to Crossdeck's ingest). */\n  endpoint?: string;\n  /** How often to flush coalesced counts (ms). Default 60_000. */\n  flushIntervalMs?: number;\n  /** Notified when a flush fails, so a dropped window is never silent. */\n  onError?: WebMeterConfig[\"onError\"];\n}\n\n/** Configure the browser collector once, at app start. */\nexport function initBucketsWeb(options: InitWebOptions): void {\n  const sink = new WebReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureWebMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n}\n\n// The tagging verb + the metered read wrappers.\nexport { bucket } from \"./context\";\nexport { getDoc, getDocs, onSnapshot } from \"./firestore\";\nexport { flushWeb as flush } from \"./meter\";\n\n// The sink seam — for self-hosting the browser rollups instead of reporting to Crossdeck.\nexport { WebReportSink, type WebReportSinkConfig } from \"./sink\";\nexport type { BucketsReport, OpCounts, Sink } from \"../sink\";\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cross-deck/buckets",
-  "version": "0.1.2",
-  "description": "Know exactly what every database read costs you — and who caused it. A tiny, never-throws read-cost collector for Firestore.",
+  "version": "0.2.1",
+  "description": "Know exactly what every database read costs you — and who caused it. A tiny, never-throws read-cost collector for Firestore, server AND browser.",
   "license": "MIT",
   "author": "Crossdeck",
   "main": "./dist/index.js",
@@ -12,6 +12,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./web": {
+      "types": "./dist/web.d.ts",
+      "import": "./dist/web.mjs",
+      "require": "./dist/web.js"
     }
   },
   "files": [
@@ -48,9 +53,13 @@
     "url": "https://github.com/Crossdeckhq/buckets-oss/issues"
   },
   "peerDependencies": {
+    "firebase": ">=9",
     "firebase-admin": ">=11"
   },
   "peerDependenciesMeta": {
+    "firebase": {
+      "optional": true
+    },
     "firebase-admin": {
       "optional": true
     }
@@ -60,7 +69,8 @@
     "firebase-admin": "^12.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "vitest": "^1.6.0",
+    "firebase": "^10.0.0"
   },
   "engines": {
     "node": ">=18"