API Reference

getReadStats(scope?)

Returns read statistics for the current page (default, reset on every navigation) or for the whole dev session with 'session'.

Returns: Object with totalReads, pageReads, sessionReads, callers (every read source, sorted by reads), topCollections, worstOffender, and since 1.4 writes, deletes (for the scope), pageWrites, pageDeletes, sessionWrites, sessionDeletes and writeSources (every write source, sorted by writes and deletes)

const stats = window.ReadMeter.getReadStats()           // this page
const all = window.ReadMeter.getReadStats('session')    // whole dev session
// { scope: 'page', page: '/home', totalReads: 42, callers: [{ caller, collection, type, reads, executions, pages }], ... }

resetReads()

Resets page and session counters to zero.

window.ReadMeter.resetReads()

subscribe(callback)

Subscribe to read updates. Called whenever a new read is recorded.

Returns: Unsubscribe function

const unsub = window.ReadMeter.subscribe(() => {
  console.log('Reads:', window.ReadMeter.getReadStats().totalReads)
})
unsub() // stop listening

recordRead(op)

Record a read from external code (e.g. modular SDK wrapper or your own tracker). Not needed when using the compat SDK — the widget patches Firestore automatically.

Parameter shape: op — object with:

• reads (number, required) — number of document reads
• collection (string, required) — collection name
• type (string, optional) — e.g. 'getDoc', 'getDocs', 'onSnapshot'
• caller (string, optional) — e.g. feature name or file:line
• page (string, optional) — page path (e.g. /dashboard). Defaults to window.location.pathname if omitted

window.ReadMeter.recordRead({
  reads: 10,
  collection: 'users',
  type: 'getDocs',
  caller: 'loadUsers (App.tsx:42)'
})

Bridge from existing tracker: If you already track reads (e.g. firestoreReadTracker.track()), add: window.ReadMeter?.recordRead({ reads, collection, type, caller })

recordWrite(op)

Record writes and deletes from external code. The modular SDK wrapper calls it for setDoc, addDoc, updateDoc, deleteDoc, writeBatch and runTransaction once each write succeeds. Firestore bills writes and deletes separately, one per document, so they are counted apart. Same shape as recordRead, with writes and deletes (numbers) in place of reads.

window.ReadMeter.recordWrite({
  writes: 2,
  deletes: 1,
  collection: 'posts',
  type: 'writeBatch',
  caller: 'archivePosts (posts.ts:88)'
})

The widget prices them at writeCostPer100k (default $0.18) and deleteCostPer100k (default $0.02); set either in window.ReadMeter = { config: { … } } like costPer100k. Reads still drive the page's risk level.

setLocale(locale)

Switch the widget language: 'en', 'de', 'es' or 'tr'. By default the widget uses your browser language, and you can also pick one in its settings. To fix a language for everyone on a project, set window.ReadMeter = { config: { locale: 'de' } } before the script loads. The "fix prompt" for AI tools stays in English. getLocale() returns the current language.

window.ReadMeter.setLocale('de')

init()

Manually initialize the widget (normally runs on DOMContentLoaded).

window.ReadMeter.init()

instrumentAdminFirestore(db)

Wraps a firebase-admin Firestore instance so .get() / getAll() record estimated document reads, and set() / create() / update() / delete(), add(), batch(), runTransaction() and bulkWriter() (counted on flush() / close()) record writes and deletes. recursiveDelete() is not counted. Idempotent.

import { getFirestore } from 'firebase-admin/firestore'
import { instrumentAdminFirestore } from '@/lib/readmeter-admin-firestore'

export const db = instrumentAdminFirestore(getFirestore())

getAdminReadStats() / resetAdminReadStats()

Process-local stats: totalReads, byCollection, byType, totalWrites, totalDeletes, writesByCollection, writesByType, recentOperations (writes show reads: 0 with writes / deletes).

GET /api/readmeter-admin

Added on Next.js init. Returns getAdminReadStats() JSON in development. ?reset=1 clears counters. Production returns 404 unless READMETER_ADMIN_API=1. Optional console: READMETER_ADMIN_LOG=1.