@cross-deck/buckets 0.2.2 → 0.3.0

package/README.md

@@ -379,6 +379,8 @@ maintained summary, never scans your data.
 | Empty query | 1 read *(your provider bills a minimum of one)* |
 | `doc.get()` | 1 read |
 | `getAll(...refs)` | one read per ref |
+| `onSnapshot` fire (server + browser) | the docs that fire delivered |
+| `count()` / aggregation | ~`ceil(matched / 1000)` reads *(honest estimate — Firestore doesn't expose the exact index-entry count)* |
 | Write / delete | 1 each |
 
 Counts are **defensible** — every one traces to a billed operation, so the rollup

package/dist/index.d.mts

@@ -33,11 +33,13 @@ interface FirestoreClasses {
     Query?: {
         prototype: {
             get?: AnyFn;
+            onSnapshot?: AnyFn;
         };
     };
     DocumentReference?: {
         prototype: {
             get?: AnyFn;
+            onSnapshot?: AnyFn;
         };
     };
     Transaction?: {
@@ -51,6 +53,12 @@ interface FirestoreClasses {
             getAll?: AnyFn;
         };
     };
+    /** count() / sum() / average() — aggregation queries bill reads too. */
+    AggregateQuery?: {
+        prototype: {
+            get?: AnyFn;
+        };
+    };
 }
 /**
  * Install the universal read meter on the firebase-admin Firestore classes. Call

package/dist/index.d.ts

@@ -33,11 +33,13 @@ interface FirestoreClasses {
     Query?: {
         prototype: {
             get?: AnyFn;
+            onSnapshot?: AnyFn;
         };
     };
     DocumentReference?: {
         prototype: {
             get?: AnyFn;
+            onSnapshot?: AnyFn;
         };
     };
     Transaction?: {
@@ -51,6 +53,12 @@ interface FirestoreClasses {
             getAll?: AnyFn;
         };
     };
+    /** count() / sum() / average() — aggregation queries bill reads too. */
+    AggregateQuery?: {
+        prototype: {
+            get?: AnyFn;
+        };
+    };
 }
 /**
  * Install the universal read meter on the firebase-admin Firestore classes. Call

package/dist/index.js

@@ -183,7 +183,7 @@ function meterCount(n, hint) {
 function installFirestoreMeter(classes) {
   if (installed) return;
   installed = true;
-  const { Query, DocumentReference, Transaction, Firestore } = classes;
+  const { Query, DocumentReference, Transaction, Firestore, AggregateQuery } = classes;
   const qGet = Query?.prototype?.get;
   if (qGet) {
     Query.prototype.get = async function(...args) {
@@ -224,6 +224,41 @@ function installFirestoreMeter(classes) {
       return res;
     };
   }
+  const aGet = AggregateQuery?.prototype?.get;
+  if (aGet) {
+    AggregateQuery.prototype.get = async function(...args) {
+      const snap = await aGet.apply(this, args);
+      try {
+        const data = snap?.data?.();
+        const count = typeof data?.count === "number" ? data.count : 0;
+        meterCount(Math.max(1, Math.ceil(count / 1e3)), hintFrom(this));
+      } catch {
+      }
+      return snap;
+    };
+  }
+  const patchOnSnapshot = (proto, perDoc) => {
+    const real = proto?.onSnapshot;
+    if (!real) return;
+    proto.onSnapshot = function(...args) {
+      const hint = hintFrom(this);
+      const i = args.findIndex((a) => typeof a === "function");
+      if (i >= 0) {
+        const onNext = args[i];
+        args[i] = function(snap) {
+          try {
+            const n = perDoc ? 1 : typeof snap?.docChanges === "function" ? snap.docChanges().length : typeof snap?.size === "number" ? snap.size : 1;
+            if (n > 0) meterCount(n, hint);
+          } catch {
+          }
+          return onNext(snap);
+        };
+      }
+      return real.apply(this, args);
+    };
+  };
+  patchOnSnapshot(Query?.prototype, false);
+  patchOnSnapshot(DocumentReference?.prototype, true);
 }
 
 // src/index.ts

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["AsyncLocalStorage","sink"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> 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;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): 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 ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\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    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", 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/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\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    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\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 report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\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  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}
+{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["AsyncLocalStorage","sink"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> 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;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): 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 ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\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    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", 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/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\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    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\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 report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn; onSnapshot?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn; onSnapshot?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n  /** count() / sum() / average() — aggregation queries bill reads too. */\n  AggregateQuery?: { prototype: { get?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore, AggregateQuery } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // AggregateQuery.get — count() / sum() / average(). Firestore bills one read per\n  // up to 1000 index entries scanned, and the client never sees that entry count —\n  // so this is an HONEST ESTIMATE: for count() we derive it from the result\n  // (ceil(count / 1000)), else the billed minimum of 1. Observe-only: it reads the\n  // result you already got, adds zero reads. (Closes the aggregation blind spot.)\n  const aGet = AggregateQuery?.prototype?.get;\n  if (aGet) {\n    AggregateQuery!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await aGet.apply(this, args);\n      try {\n        const data = (snap as { data?: () => { count?: number } } | null)?.data?.();\n        const count = typeof data?.count === \"number\" ? data.count : 0;\n        meterCount(Math.max(1, Math.ceil(count / 1000)), hintFrom(this));\n      } catch {\n        /* best-effort */\n      }\n      return snap;\n    };\n  }\n\n  // Query.onSnapshot / DocumentReference.onSnapshot — server-side realtime\n  // listeners. We OBSERVE: wrap onNext and count the docs each fire delivers (a\n  // query's changed docs — first fire = all matching; a doc = 1). We attach no\n  // listener and issue no read; the meter just sees what the listener is already\n  // billed. (Closes the server-listener blind spot.)\n  const patchOnSnapshot = (proto: { onSnapshot?: AnyFn } | undefined, perDoc: boolean): void => {\n    const real = proto?.onSnapshot;\n    if (!real) return;\n    proto!.onSnapshot = function (this: unknown, ...args: any[]) {\n      const hint = hintFrom(this);\n      const i = args.findIndex((a) => typeof a === \"function\");\n      if (i >= 0) {\n        const onNext = args[i];\n        args[i] = function (snap: any) {\n          try {\n            const n = perDoc\n              ? 1\n              : typeof snap?.docChanges === \"function\"\n                ? snap.docChanges().length\n                : typeof snap?.size === \"number\"\n                  ? snap.size\n                  : 1;\n            if (n > 0) meterCount(n, hint);\n          } catch {\n            /* best-effort */\n          }\n          return onNext(snap);\n        };\n      }\n      return real.apply(this, args);\n    };\n  };\n  patchOnSnapshot(Query?.prototype, false);\n  patchOnSnapshot(DocumentReference?.prototype, true);\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\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  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}

package/dist/index.mjs

@@ -181,7 +181,7 @@ function meterCount(n, hint) {
 function installFirestoreMeter(classes) {
   if (installed) return;
   installed = true;
-  const { Query, DocumentReference, Transaction, Firestore } = classes;
+  const { Query, DocumentReference, Transaction, Firestore, AggregateQuery } = classes;
   const qGet = Query?.prototype?.get;
   if (qGet) {
     Query.prototype.get = async function(...args) {
@@ -222,6 +222,41 @@ function installFirestoreMeter(classes) {
       return res;
     };
   }
+  const aGet = AggregateQuery?.prototype?.get;
+  if (aGet) {
+    AggregateQuery.prototype.get = async function(...args) {
+      const snap = await aGet.apply(this, args);
+      try {
+        const data = snap?.data?.();
+        const count = typeof data?.count === "number" ? data.count : 0;
+        meterCount(Math.max(1, Math.ceil(count / 1e3)), hintFrom(this));
+      } catch {
+      }
+      return snap;
+    };
+  }
+  const patchOnSnapshot = (proto, perDoc) => {
+    const real = proto?.onSnapshot;
+    if (!real) return;
+    proto.onSnapshot = function(...args) {
+      const hint = hintFrom(this);
+      const i = args.findIndex((a) => typeof a === "function");
+      if (i >= 0) {
+        const onNext = args[i];
+        args[i] = function(snap) {
+          try {
+            const n = perDoc ? 1 : typeof snap?.docChanges === "function" ? snap.docChanges().length : typeof snap?.size === "number" ? snap.size : 1;
+            if (n > 0) meterCount(n, hint);
+          } catch {
+          }
+          return onNext(snap);
+        };
+      }
+      return real.apply(this, args);
+    };
+  };
+  patchOnSnapshot(Query?.prototype, false);
+  patchOnSnapshot(DocumentReference?.prototype, true);
 }
 
 // src/index.ts

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["sink"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> 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;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): 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 ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\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    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", 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/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\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    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\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 report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\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  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}
+{"version":3,"sources":["../src/cost-context.ts","../src/cost-meter.ts","../src/sink.ts","../src/adapters/firestore.ts","../src/index.ts"],"names":["sink"],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * cost-context — the request-scoped tag every counted operation attributes\n * itself to. Set it ONCE at a boundary (or wrap a path with `bucket()`); it\n * rides Node's AsyncLocalStorage down through every async fan-out, so one\n * handler that triggers 15 reads attributes all 15 to the same bucket — with\n * zero per-call-site work.\n *\n * Generic by design: unlike a hardcoded product taxonomy, the only meaningful\n * field a consumer sets is the free-form `label` (the bucket name). `feature`\n * is an optional coarse grouping if you want one; nothing here is\n * Crossdeck-specific.\n */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\n\nexport interface CostTag {\n  /** Optional coarse grouping (a caller-defined surface name). */\n  feature?: string;\n  /** The bucket name — what `bucket()` sets. Drives the report's `byLabel`. */\n  label?: string;\n}\n\nconst DEFAULT_TAG: CostTag = {};\nconst store = new AsyncLocalStorage<CostTag>();\n\n/** Run `fn` with `tag` bound for its entire async subtree. */\nexport function runWithCostTag<T>(tag: CostTag, fn: () => T): T {\n  return store.run({ ...tag }, fn);\n}\n\n/** Bind a tag for the remainder of the current async context (no closure to wrap). */\nexport function enterCostTag(tag: CostTag): void {\n  store.enterWith({ ...tag });\n}\n\n/** Refine the live tag in place (e.g. stamp a feature after the boundary). */\nexport function refineCostTag(patch: Partial<CostTag>): void {\n  const cur = store.getStore();\n  if (cur) Object.assign(cur, patch);\n}\n\n/** The current tag, or a safe empty default outside any bound context. */\nexport function currentCostTag(): CostTag {\n  return store.getStore() ?? DEFAULT_TAG;\n}\n\n/**\n * `bucket(name, fn)` — the headline verb, the `track()` of cost. Run `fn` with\n * every operation inside it attributed to the bucket `name`; the attribution\n * rides the async subtree automatically. The one verb most developers ever touch:\n *\n *   await bucket(\"nightly-export\", async () => {\n *     const rows = await db.collection(\"events\").where(...).get(); // → \"nightly-export\"\n *   });\n */\nexport function bucket<T>(name: string, fn: () => T): T {\n  return runWithCostTag({ ...currentCostTag(), label: name }, fn);\n}\n","/**\n * cost-meter — counts operations against the ambient tag and flushes them to the\n * configured Sink cheaply.\n *\n * LOW-OVERHEAD CONTRACT (the thing that warns you about reads must not run them\n * up): counts accumulate in an in-memory buffer and flush periodically — NEVER one\n * network call per counted operation. A flush coalesces the whole window into one\n * report per UTC day and hands it to the Sink. At steady state that is ~1 small\n * request a minute, regardless of how many ops you served.\n *\n * BEST-EFFORT CONTRACT: metering must never throw into your code. Every recorder\n * swallows its own errors; a failed flush drops that window's counts (surfaced via\n * `onError` if you pass one) rather than disturbing the app.\n */\nimport { currentCostTag } from \"./cost-context\";\nimport type { Sink, BucketsReport, OpCounts } from \"./sink\";\n\nexport type OpType = \"read\" | \"write\" | \"delete\";\n\n/** Optional read-site hint — the collection touched, derived at the trap from the\n *  path. Lets an UNtagged read cascade to `col:<collection>` instead of vanishing. */\nexport interface CostHint {\n  collection?: string;\n  projectId?: string;\n}\n\n// NUL separator — a bucket/collection name can contain almost anything except\n// this, so the key never collides with a name that has a \"|\" or \":\" in it.\nconst SEP = \"\\u001f\"; // ASCII Unit Separator\n\n/** key = date <NUL> op <NUL> label → count */\nconst labelBuffer = new Map<string, number>();\n/** key = date <NUL> op <NUL> 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;\n/** Safety valve — flush early if a burst fills the buffer between intervals. */\nconst MAX_BUFFER_KEYS = 5_000;\n\nexport interface MeterConfig {\n  sink: Sink;\n  flushIntervalMs?: number;\n  onError?: (e: unknown) => void;\n}\n\n/** Point the meter at a sink. Called by `init()`; pass your own sink to self-host. */\nexport function configureMeter(config: MeterConfig): 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 ensureFlushLoop(): void {\n  if (timer) return;\n  timer = setInterval(() => void flush(), flushIntervalMs);\n  // Don't keep the event loop alive just for metering.\n  (timer as { unref?: () => void }).unref?.();\n  // Flush the last window on shutdown.\n  process.once?.(\"SIGTERM\", () => void flush());\n  process.once?.(\"beforeExit\", () => void flush());\n}\n\n/** Count `n` ops of `op` against the live tag. Never throws. */\nexport function recordFirestore(op: OpType, n: number, hint?: CostHint): void {\n  try {\n    if (!Number.isFinite(n) || n <= 0) return;\n    const t = currentCostTag();\n    const date = utcDate();\n    // CASCADE — every op gets a label, by design (no blind spots): the bucket name\n    // wins; else the collection it actually touched (`col:posts`); else\n    // \"uncategorized\" as a loud last resort. A read is never invisible.\n    const label = t.label || (hint?.collection ? `col:${hint.collection}` : \"uncategorized\");\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    ensureFlushLoop();\n    if (labelBuffer.size + hourBuffer.size > MAX_BUFFER_KEYS) void flush();\n  } catch {\n    /* metering is best-effort — never disturb the caller */\n  }\n}\n\n/** Firestore bills a minimum of one read even for an empty result, so 0 counts as 1. */\nexport function recordReads(n: number, hint?: CostHint): void {\n  recordFirestore(\"read\", Math.max(n, 1), hint);\n}\nexport function recordWrites(n = 1): void {\n  recordFirestore(\"write\", n);\n}\nexport function recordDeletes(n = 1): void {\n  recordFirestore(\"delete\", 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/**\n * Coalesce the buffer into one report per UTC day and hand each to the Sink.\n * Snapshots + clears up front so concurrent records land in the next window.\n * Never throws; a sink failure drops that window (surfaced via `onError`).\n */\nexport async function flush(): Promise<void> {\n  if (flushing) return;\n  // Not configured (init not called) — drop, don't grow unbounded.\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    // Drop this window rather than risk a partial/double report on retry.\n    onError?.(e);\n  } finally {\n    flushing = false;\n  }\n}\n","/**\n * sink — where the meter sends a coalesced rollup, and the wire shape it sends.\n *\n * Abstracting the sink is what makes Buckets storage-agnostic: the meter never\n * knows where counts go. The DEFAULT sink (`ReportSink`) reports up to Crossdeck's\n * ingest endpoint so the numbers surface on your Crossdeck dashboard. A team that\n * wants to self-host can implement `Sink` against anything (Postgres, a file, your\n * own API) without touching the meter.\n */\n\nexport interface OpCounts {\n  read?: number;\n  write?: number;\n  delete?: number;\n}\n\n/**\n * One coalesced report — the wire contract (see docs/ROLLUP_SCHEMA.md). The meter\n * produces one of these per UTC day in a flush window (usually exactly one).\n */\nexport interface BucketsReport {\n  /** UTC day \"YYYY-MM-DD\". */\n  date: string;\n  /** bucket name → counts. The heart of the report. */\n  byLabel: Record<string, OpCounts>;\n  /** UTC hour \"HH\" → counts, for the hourly \"did my fix land this hour?\" view. */\n  byHour?: Record<string, OpCounts>;\n}\n\n/**\n * A destination for coalesced rollups. `flush` MAY throw on failure — the meter\n * catches it, drops that one window, and never lets it reach your app.\n */\nexport interface Sink {\n  flush(report: BucketsReport): Promise<void>;\n}\n\nexport interface ReportSinkConfig {\n  /** The project's `cd_sk_` secret key. Server-to-server only. */\n  apiKey: string;\n  /** Defaults to https://api.cross-deck.com/v1/buckets/report */\n  endpoint?: string;\n  /** Request timeout (ms); a slow Crossdeck must never stall your flush. */\n  timeoutMs?: number;\n}\n\nconst DEFAULT_ENDPOINT = \"https://api.cross-deck.com/v1/buckets/report\";\n\n/**\n * The default sink: POST one coalesced rollup to Crossdeck's ingest endpoint.\n * The ingest folds it into the day's maintained doc with `increment`, so many\n * reports a minute coalesce safely. This path does ZERO database reads — it sends\n * a summary, it does not read. Throws on a non-202 so the meter can log/drop the\n * window; the meter guarantees it never reaches your app.\n */\nexport class ReportSink implements Sink {\n  private readonly endpoint: string;\n  private readonly apiKey: string;\n  private readonly timeoutMs: number;\n\n  constructor(config: ReportSinkConfig) {\n    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;\n    this.apiKey = config.apiKey;\n    this.timeoutMs = config.timeoutMs ?? 5000;\n  }\n\n  async flush(report: BucketsReport): Promise<void> {\n    const res = await fetch(this.endpoint, {\n      method: \"POST\",\n      signal: AbortSignal.timeout(this.timeoutMs),\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 report rejected: HTTP ${res.status}`);\n    }\n  }\n}\n","/**\n * adapters/firestore — the universal Firestore read meter (the trap).\n *\n * THE LESSON (learned on a real product): per-call-site `recordReads()`\n * instrumentation MISSES paths. You meter the read sites you're looking at and\n * leave the cron / trigger / ingest path uncounted — often the majority of reads,\n * invisible. Humans tag what they see and miss the path that matters.\n *\n * THE FIX: patch the admin SDK's read methods ONCE. From install onward, EVERY\n * read — anywhere, on any code path — is counted under the ambient tag, with zero\n * per-call-site work and no blind spots.\n *\n * SAFETY CONTRACT — this sits on your production read path, so it is defensive by\n * construction. Each wrapper:\n *   1. calls the REAL method first and captures the result,\n *   2. counts in a try/catch that can never throw into the caller,\n *   3. ALWAYS returns the real result, untouched.\n * It cannot break a read, change a result, or add latency beyond one in-memory\n * counter increment. A wrong count is a measurement error, never a correctness or\n * availability one. Idempotent — calling it twice patches once.\n *\n * COUNTING MODEL — a query returning N docs = N reads (an empty result still bills\n * 1, which the meter enforces). A document get = 1. getAll(...) = the ref count.\n * CollectionReference.get IS Query.get (shared prototype method), so patching Query\n * covers collections with no double-count.\n */\nimport { recordReads, type CostHint } from \"../cost-meter\";\n\nlet installed = false;\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\ntype AnyFn = (...args: any[]) => any;\n\n/**\n * The firebase-admin Firestore classes to patch. Pass the module namespace from\n * `firebase-admin/firestore` — only the prototypes present are patched.\n */\nexport interface FirestoreClasses {\n  Query?: { prototype: { get?: AnyFn; onSnapshot?: AnyFn } };\n  DocumentReference?: { prototype: { get?: AnyFn; onSnapshot?: AnyFn } };\n  Transaction?: { prototype: { get?: AnyFn; getAll?: AnyFn } };\n  Firestore?: { prototype: { getAll?: AnyFn } };\n  /** count() / sum() / average() — aggregation queries bill reads too. */\n  AggregateQuery?: { prototype: { get?: AnyFn } };\n}\n\n/** `projects/{id}/…` → the project id, else undefined. Pure string op. */\nfunction projectFromPath(path: string): string | undefined {\n  const parts = path.split(\"/\");\n  const i = parts.indexOf(\"projects\");\n  return i >= 0 && parts[i + 1] ? parts[i + 1] : undefined;\n}\n\n/**\n * Derive { collection, projectId } from the read target's path so an UNtagged read\n * cascades to `col:<collection>` instead of \"uncategorized\". PURE CPU; never reads,\n * never throws. Falls back to firebase-admin's internal `_queryOptions` for filtered\n * queries (which don't expose `.path`).\n */\nfunction hintFrom(target: any): CostHint | undefined {\n  try {\n    const p = typeof target?.path === \"string\" ? target.path : \"\";\n    if (p) {\n      const parts = p.split(\"/\").filter(Boolean);\n      const collection = parts.length % 2 === 0 ? parts[parts.length - 2] : parts[parts.length - 1];\n      return { collection, projectId: projectFromPath(p) };\n    }\n    const qo = target?._queryOptions;\n    if (qo) {\n      const collection = typeof qo.collectionId === \"string\" ? qo.collectionId : undefined;\n      const parent =\n        typeof qo.parentPath?.relativeName === \"string\"\n          ? qo.parentPath.relativeName\n          : typeof qo.parentPath?.toString === \"function\"\n            ? String(qo.parentPath.toString())\n            : \"\";\n      return { collection, projectId: parent ? projectFromPath(parent) : undefined };\n    }\n  } catch {\n    /* the meter must never throw */\n  }\n  return undefined;\n}\n\nfunction meterSnap(snap: unknown, hint?: CostHint): void {\n  try {\n    const size = (snap as { size?: number } | null)?.size;\n    recordReads(typeof size === \"number\" ? size : 1, hint);\n  } catch {\n    /* best-effort */\n  }\n}\nfunction meterCount(n: number, hint?: CostHint): void {\n  try {\n    recordReads(n, hint);\n  } catch {\n    /* best-effort */\n  }\n}\n\n/**\n * Install the universal read meter on the firebase-admin Firestore classes. Call\n * ONCE at process start, before any reads. Pass the namespace from\n * `firebase-admin/firestore` so the exact prototypes the SDK uses are patched:\n *\n *   import * as Firestore from \"firebase-admin/firestore\";\n *   installFirestoreMeter(Firestore);\n */\nexport function installFirestoreMeter(classes: FirestoreClasses): void {\n  if (installed) return;\n  installed = true;\n  const { Query, DocumentReference, Transaction, Firestore, AggregateQuery } = classes;\n\n  // Query.get — covers Query AND CollectionReference (shared prototype method).\n  const qGet = Query?.prototype?.get;\n  if (qGet) {\n    Query!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await qGet.apply(this, args);\n      meterSnap(snap, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // DocumentReference.get — a single doc = 1 read.\n  const dGet = DocumentReference?.prototype?.get;\n  if (dGet) {\n    DocumentReference!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await dGet.apply(this, args);\n      meterCount(1, hintFrom(this));\n      return snap;\n    };\n  }\n\n  // Transaction.get — query or doc; size when present, else 1.\n  const tGet = Transaction?.prototype?.get;\n  if (tGet) {\n    Transaction!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const res = await tGet.apply(this, args);\n      meterSnap(res, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Transaction.getAll(...refs) — one read per ref.\n  const tGetAll = Transaction?.prototype?.getAll;\n  if (tGetAll) {\n    Transaction!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await tGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // Firestore.getAll(...refs) — batched doc reads.\n  const fGetAll = Firestore?.prototype?.getAll;\n  if (fGetAll) {\n    Firestore!.prototype.getAll = async function (this: unknown, ...args: any[]) {\n      const res = await fGetAll.apply(this, args);\n      meterCount(Array.isArray(res) ? res.length : args.length || 1, hintFrom(args[0]));\n      return res;\n    };\n  }\n\n  // AggregateQuery.get — count() / sum() / average(). Firestore bills one read per\n  // up to 1000 index entries scanned, and the client never sees that entry count —\n  // so this is an HONEST ESTIMATE: for count() we derive it from the result\n  // (ceil(count / 1000)), else the billed minimum of 1. Observe-only: it reads the\n  // result you already got, adds zero reads. (Closes the aggregation blind spot.)\n  const aGet = AggregateQuery?.prototype?.get;\n  if (aGet) {\n    AggregateQuery!.prototype.get = async function (this: unknown, ...args: any[]) {\n      const snap = await aGet.apply(this, args);\n      try {\n        const data = (snap as { data?: () => { count?: number } } | null)?.data?.();\n        const count = typeof data?.count === \"number\" ? data.count : 0;\n        meterCount(Math.max(1, Math.ceil(count / 1000)), hintFrom(this));\n      } catch {\n        /* best-effort */\n      }\n      return snap;\n    };\n  }\n\n  // Query.onSnapshot / DocumentReference.onSnapshot — server-side realtime\n  // listeners. We OBSERVE: wrap onNext and count the docs each fire delivers (a\n  // query's changed docs — first fire = all matching; a doc = 1). We attach no\n  // listener and issue no read; the meter just sees what the listener is already\n  // billed. (Closes the server-listener blind spot.)\n  const patchOnSnapshot = (proto: { onSnapshot?: AnyFn } | undefined, perDoc: boolean): void => {\n    const real = proto?.onSnapshot;\n    if (!real) return;\n    proto!.onSnapshot = function (this: unknown, ...args: any[]) {\n      const hint = hintFrom(this);\n      const i = args.findIndex((a) => typeof a === \"function\");\n      if (i >= 0) {\n        const onNext = args[i];\n        args[i] = function (snap: any) {\n          try {\n            const n = perDoc\n              ? 1\n              : typeof snap?.docChanges === \"function\"\n                ? snap.docChanges().length\n                : typeof snap?.size === \"number\"\n                  ? snap.size\n                  : 1;\n            if (n > 0) meterCount(n, hint);\n          } catch {\n            /* best-effort */\n          }\n          return onNext(snap);\n        };\n      }\n      return real.apply(this, args);\n    };\n  };\n  patchOnSnapshot(Query?.prototype, false);\n  patchOnSnapshot(DocumentReference?.prototype, true);\n}\n\n/** Test-only: reset the install guard so a suite can re-patch fresh prototypes. */\nexport function __resetFirestoreMeterForTests(): void {\n  installed = false;\n}\n","/**\n * @cross-deck/buckets — know exactly what every database read costs you, and who\n * caused it. A tiny, never-throws collector for Firestore.\n *\n * The whole footprint a consumer sees:\n *   1. init({ apiKey, firestore })  — configure once, install the trap once\n *   2. bucket(name, fn)             — name the read paths that matter\n *   3. (the dashboard shows the rest — and names the ones you haven't yet)\n */\nimport { configureMeter, type MeterConfig } from \"./cost-meter\";\nimport { ReportSink, type Sink } from \"./sink\";\nimport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\nexport interface InitOptions {\n  /** The project's `cd_sk_` SECRET key. Server-to-server only — never a browser key. */\n  apiKey: string;\n  /**\n   * Pass the namespace from `firebase-admin/firestore` to auto-install the read\n   * trap (recommended — this is what makes every read count with no per-call work).\n   * Omit it if you'd rather call `installFirestoreMeter()` yourself, or you only\n   * use the manual `recordReads()` recorders.\n   */\n  firestore?: FirestoreClasses;\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  /** Bring your own sink (self-host the rollups). Defaults to reporting up to Crossdeck. */\n  sink?: Sink;\n  /** Notified when a flush fails, so a dropped window is never silent. Best-effort. */\n  onError?: MeterConfig[\"onError\"];\n}\n\n/**\n * Configure Buckets once, at process start. Points the meter at a sink (Crossdeck's\n * ingest by default) and — if you pass `firestore` — installs the universal read\n * trap so every read counts automatically.\n */\nexport function init(options: InitOptions): void {\n  const sink = options.sink ?? new ReportSink({ apiKey: options.apiKey, endpoint: options.endpoint });\n  configureMeter({ sink, flushIntervalMs: options.flushIntervalMs, onError: options.onError });\n  if (options.firestore) installFirestoreMeter(options.firestore);\n}\n\n/** Alias — reads well next to `bucket()` at a call site. */\nexport { init as initBuckets };\n\n// The headline verb + the lower-level tag controls it is sugar over.\nexport {\n  bucket,\n  runWithCostTag,\n  enterCostTag,\n  refineCostTag,\n  currentCostTag,\n  type CostTag,\n} from \"./cost-context\";\n\n// Manual recorders (for non-Firestore ops, or when you don't install the trap).\nexport {\n  recordReads,\n  recordWrites,\n  recordDeletes,\n  flush,\n  type CostHint,\n  type OpType,\n  type MeterConfig,\n} from \"./cost-meter\";\n\n// The trap (the only datastore adapter today) + its class shape.\nexport { installFirestoreMeter, type FirestoreClasses } from \"./adapters/firestore\";\n\n// The sink seam — for self-hosting rollups instead of reporting to Crossdeck.\nexport { ReportSink, type Sink, type BucketsReport, type OpCounts, type ReportSinkConfig } from \"./sink\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cross-deck/buckets",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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",