@progressive-development/pd-provider-firebase-functions 1.2.0 → 1.3.1

package/dist/script-helpers.js

@@ -1,52 +1,63 @@
-import { getApps, initializeApp, cert } from 'firebase-admin/app';
-import { existsSync, readFileSync } from 'fs';
-import { getDb } from './firestore.js';
-
-const LOG_PREFIX = {
-  info: "i ",
-  success: "OK",
-  error: "X ",
-  warn: "! "
+import { getDb } from "./firestore.js";
+import { cert, getApps, initializeApp } from "firebase-admin/app";
+import { existsSync, readFileSync } from "fs";
+//#region src/script-helpers.ts
+/**
+* Shared helpers for Firebase Admin scripts.
+*
+* Provides common boilerplate: logging, service-account validation,
+* Firebase init, Firestore access, and dry-run handling.
+*/
+var LOG_PREFIX = {
+	info: "i ",
+	success: "OK",
+	error: "X ",
+	warn: "! "
 };
+/**
+* Print a prefixed log message to console.
+*/
 function scriptLog(message, type = "info") {
-  console.log(`${LOG_PREFIX[type]} ${message}`);
+	console.log(`${LOG_PREFIX[type]} ${message}`);
 }
+/**
+* Initialize Firebase Admin SDK if not already initialized.
+*/
 function initFirebaseAdmin(serviceAccountPath) {
-  if (getApps().length > 0) return;
-  const serviceAccount = JSON.parse(
-    readFileSync(serviceAccountPath, "utf-8")
-  );
-  initializeApp({
-    credential: cert(serviceAccount),
-    databaseURL: `https://${serviceAccount.projectId}.firebaseio.com`
-  });
+	if (getApps().length > 0) return;
+	const serviceAccount = JSON.parse(readFileSync(serviceAccountPath, "utf-8"));
+	initializeApp({
+		credential: cert(serviceAccount),
+		databaseURL: `https://${serviceAccount.projectId}.firebaseio.com`
+	});
 }
+/**
+* Set up a script context: validates paths, initializes Firebase,
+* returns a ready-to-use Firestore instance.
+*
+* Prints title, connection info, and dry-run banner.
+* Calls `process.exit(1)` if the service account key is missing.
+*/
 function createScriptContext(config) {
-  const { title, serviceAccountPath, databaseId, dryRun = false } = config;
-  console.log(`
-${title}
-`);
-  console.log("-".repeat(50));
-  if (!existsSync(serviceAccountPath)) {
-    scriptLog("Service Account Key not found!", "error");
-    console.log(`
-   Expected: ${serviceAccountPath}`);
-    console.log(`
-   Download from Firebase Console:`);
-    console.log(
-      `   Project Settings > Service Accounts > Generate new private key
-`
-    );
-    process.exit(1);
-  }
-  initFirebaseAdmin(serviceAccountPath);
-  const db = getDb(databaseId);
-  scriptLog(`Firestore: ${databaseId ?? "(default)"}`);
-  if (dryRun) {
-    scriptLog("DRY RUN - No changes will be made", "warn");
-  }
-  console.log("-".repeat(50));
-  return { db, dryRun };
+	const { title, serviceAccountPath, databaseId, dryRun = false } = config;
+	console.log(`\n${title}\n`);
+	console.log("-".repeat(50));
+	if (!existsSync(serviceAccountPath)) {
+		scriptLog("Service Account Key not found!", "error");
+		console.log(`\n   Expected: ${serviceAccountPath}`);
+		console.log(`\n   Download from Firebase Console:`);
+		console.log(`   Project Settings > Service Accounts > Generate new private key\n`);
+		process.exit(1);
+	}
+	initFirebaseAdmin(serviceAccountPath);
+	const db = getDb(databaseId);
+	scriptLog(`Firestore: ${databaseId ?? "(default)"}`);
+	if (dryRun) scriptLog("DRY RUN - No changes will be made", "warn");
+	console.log("-".repeat(50));
+	return {
+		db,
+		dryRun
+	};
 }
-
+//#endregion
 export { createScriptContext, initFirebaseAdmin, scriptLog };

package/dist/trash.js

@@ -1,83 +1,116 @@
-import { Timestamp } from 'firebase-admin/firestore';
-import { getDb } from './firestore.js';
-import { NotFoundError } from './errors.js';
-
-const TRASH_COLLECTION = "_trash";
+import { NotFoundError } from "./errors.js";
+import { getDb } from "./firestore.js";
+import { Timestamp } from "firebase-admin/firestore";
+//#region src/trash.ts
+var TRASH_COLLECTION = "_trash";
+/**
+* Move a document to trash.
+*
+* Atomically:
+* 1. Reads the original document
+* 2. Creates a trash entry with metadata
+* 3. Deletes the original document
+*
+* @param collection - The collection path (e.g., "djRequests")
+* @param documentId - The document ID to trash
+* @param deletedBy - UID of the deleting user, or a { uid, name } stamp
+*   (the name is denormalized into the trash item)
+* @param objectType - Type identifier for filtering (e.g., "djRequest")
+* @param databaseId - Optional named database
+* @returns The created trash item
+* @throws NotFoundError if document doesn't exist
+*/
 async function moveToTrash(collection, documentId, deletedBy, objectType, databaseId) {
-  const db = getDb(databaseId);
-  const originalRef = db.collection(collection).doc(documentId);
-  const trashRef = db.collection(TRASH_COLLECTION).doc();
-  return db.runTransaction(async (transaction) => {
-    const originalDoc = await transaction.get(originalRef);
-    if (!originalDoc.exists) {
-      throw new NotFoundError(`Document ${collection}/${documentId} not found`);
-    }
-    const originalData = originalDoc.data();
-    const trashData = {
-      originalId: documentId,
-      originalCollection: collection,
-      objectType,
-      deletedAt: Timestamp.now(),
-      deletedBy: typeof deletedBy === "string" ? deletedBy : deletedBy.uid,
-      ...typeof deletedBy === "object" && {
-        deletedByName: deletedBy.name
-      },
-      data: originalData
-    };
-    transaction.set(trashRef, trashData);
-    transaction.delete(originalRef);
-    return {
-      id: trashRef.id,
-      ...trashData
-    };
-  });
+	const db = getDb(databaseId);
+	const originalRef = db.collection(collection).doc(documentId);
+	const trashRef = db.collection(TRASH_COLLECTION).doc();
+	return db.runTransaction(async (transaction) => {
+		const originalDoc = await transaction.get(originalRef);
+		if (!originalDoc.exists) throw new NotFoundError(`Document ${collection}/${documentId} not found`);
+		const originalData = originalDoc.data();
+		const trashData = {
+			originalId: documentId,
+			originalCollection: collection,
+			objectType,
+			deletedAt: Timestamp.now(),
+			deletedBy: typeof deletedBy === "string" ? deletedBy : deletedBy.uid,
+			...typeof deletedBy === "object" && { deletedByName: deletedBy.name },
+			data: originalData
+		};
+		transaction.set(trashRef, trashData);
+		transaction.delete(originalRef);
+		return {
+			id: trashRef.id,
+			...trashData
+		};
+	});
 }
+/**
+* Restore a document from trash to its original location.
+*
+* Atomically:
+* 1. Reads the trash entry
+* 2. Recreates the original document
+* 3. Deletes the trash entry
+*
+* @param trashItemId - The trash document ID
+* @param databaseId - Optional named database
+* @throws NotFoundError if trash item doesn't exist
+*/
 async function restoreFromTrash(trashItemId, databaseId) {
-  const db = getDb(databaseId);
-  const trashRef = db.collection(TRASH_COLLECTION).doc(trashItemId);
-  await db.runTransaction(async (transaction) => {
-    const trashDoc = await transaction.get(trashRef);
-    if (!trashDoc.exists) {
-      throw new NotFoundError(`Trash item ${trashItemId} not found`);
-    }
-    const trashData = trashDoc.data();
-    const originalRef = db.collection(trashData.originalCollection).doc(trashData.originalId);
-    transaction.set(originalRef, trashData.data);
-    transaction.delete(trashRef);
-  });
+	const db = getDb(databaseId);
+	const trashRef = db.collection(TRASH_COLLECTION).doc(trashItemId);
+	await db.runTransaction(async (transaction) => {
+		const trashDoc = await transaction.get(trashRef);
+		if (!trashDoc.exists) throw new NotFoundError(`Trash item ${trashItemId} not found`);
+		const trashData = trashDoc.data();
+		const originalRef = db.collection(trashData.originalCollection).doc(trashData.originalId);
+		transaction.set(originalRef, trashData.data);
+		transaction.delete(trashRef);
+	});
 }
+/**
+* Permanently delete a document from trash.
+*
+* @param trashItemId - The trash document ID
+* @param databaseId - Optional named database
+* @throws NotFoundError if trash item doesn't exist
+*/
 async function permanentDelete(trashItemId, databaseId) {
-  const db = getDb(databaseId);
-  const trashRef = db.collection(TRASH_COLLECTION).doc(trashItemId);
-  const trashDoc = await trashRef.get();
-  if (!trashDoc.exists) {
-    throw new NotFoundError(`Trash item ${trashItemId} not found`);
-  }
-  await trashRef.delete();
+	const trashRef = getDb(databaseId).collection(TRASH_COLLECTION).doc(trashItemId);
+	if (!(await trashRef.get()).exists) throw new NotFoundError(`Trash item ${trashItemId} not found`);
+	await trashRef.delete();
 }
+/**
+* List items in trash, optionally filtered by object type.
+*
+* @param objectType - Optional filter by object type
+* @param limit - Maximum items to return (default: 100)
+* @param databaseId - Optional named database
+* @returns Array of trash items, newest first
+*/
 async function listTrash(objectType, limit = 100, databaseId) {
-  const db = getDb(databaseId);
-  let query = db.collection(TRASH_COLLECTION).orderBy("deletedAt", "desc").limit(limit);
-  if (objectType) {
-    query = query.where("objectType", "==", objectType);
-  }
-  const snapshot = await query.get();
-  return snapshot.docs.map((doc) => ({
-    id: doc.id,
-    ...doc.data()
-  }));
+	let query = getDb(databaseId).collection(TRASH_COLLECTION).orderBy("deletedAt", "desc").limit(limit);
+	if (objectType) query = query.where("objectType", "==", objectType);
+	return (await query.get()).docs.map((doc) => ({
+		id: doc.id,
+		...doc.data()
+	}));
 }
+/**
+* Get a single trash item by ID.
+*
+* @param trashItemId - The trash document ID
+* @param databaseId - Optional named database
+* @returns The trash item or null if not found
+*/
 async function getTrashItem(trashItemId, databaseId) {
-  const db = getDb(databaseId);
-  const trashRef = db.collection(TRASH_COLLECTION).doc(trashItemId);
-  const doc = await trashRef.get();
-  if (!doc.exists) {
-    return null;
-  }
-  return {
-    id: doc.id,
-    ...doc.data()
-  };
+	const doc = await getDb(databaseId).collection(TRASH_COLLECTION).doc(trashItemId).get();
+	if (!doc.exists) return null;
+	return {
+		id: doc.id,
+		...doc.data()
+	};
 }
-
+//#endregion
 export { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash };

package/dist/types.js

@@ -1,11 +1,12 @@
-const StatusCode = {
-  OK: 200,
-  CREATED: 201,
-  BAD_REQUEST: 400,
-  UNAUTHORIZED: 401,
-  FORBIDDEN: 403,
-  NOT_FOUND: 404,
-  INTERNAL_ERROR: 500
+//#region src/types.ts
+var StatusCode = {
+	OK: 200,
+	CREATED: 201,
+	BAD_REQUEST: 400,
+	UNAUTHORIZED: 401,
+	FORBIDDEN: 403,
+	NOT_FOUND: 404,
+	INTERNAL_ERROR: 500
 };
-
+//#endregion
 export { StatusCode };

package/dist/visits.d.ts

@@ -0,0 +1,135 @@
+import { CallableRequest } from 'firebase-functions/v2/https';
+/**
+ * Reach measurement — one row per visitor and day.
+ *
+ * WHY ROWS AND NOT COUNTERS: a counter answers only the question you asked
+ * when you built it. Rows can still be grouped, filtered and exported later,
+ * and every value the client sends stays a field VALUE — never a field name,
+ * where a dot would silently create a nested field.
+ *
+ * HOW DEDUPLICATION WORKS: the document id is `<day>_<visitorKey>` and the row
+ * is written with `create()`. A second call on the same day hits ALREADY_EXISTS
+ * and is dropped. No read, no counter, no transaction — the storage IS the
+ * deduplication.
+ *
+ * THE DAY IS IN THE ID, NOT IN THE KEY. That is what makes returning visitors
+ * visible: same suffix on two days is the same visitor. How long that link
+ * survives is one option (`rotate`): "day" makes rows unlinkable across days,
+ * "month" lets you recognise a returning visitor within a month. Default is
+ * the private one; an app that wants recognition asks for it.
+ *
+ * WHAT THE KEY IS WORTH: it is derived from IP and user agent. A browser
+ * update changes the user agent, mobile networks rotate IPs, a household
+ * shares one — so a recognised visitor is real, but an unrecognised one may
+ * still be the same person. It is a lower bound, not a head count. With
+ * `rotate: "month"` the key is a pseudonymous identifier: two rows carrying it
+ * are the same person, which is the point and the price.
+ *
+ * `secret` is optional. Without it the key is a plain hash of values an
+ * attacker could guess, so anyone WHO ALREADY HAS THE ROWS could test whether
+ * a given IP and browser visited. Rows are readable through the Admin SDK
+ * only; adding a constant closes even that, without changing this signature.
+ */
+export type VisitDevice = "phone" | "tablet" | "desktop";
+/**
+ * What the client sends — coarse on purpose; every value is a field, not a key.
+ *
+ * Passed in SEPARATELY from the request, because an app usually wraps its calls
+ * in an envelope of its own (`{ object, type, details }`) and the payload then
+ * sits somewhere inside `request.data`. The helper reads headers from the
+ * request and takes the payload from the caller, so both shapes fit.
+ */
+export interface VisitInput {
+    /** Coarse device class, e.g. from a pointer/width media query. */
+    device?: VisitDevice;
+    /** Opened as an installed app (display-mode: standalone). */
+    standalone?: boolean;
+    /** Host of the referrer, reduced by the client. Never a full URL. */
+    referrer?: string;
+}
+export interface CountVisitOptions {
+    /**
+     * Count only calls from these origins — keeps dev servers out of the numbers.
+     * A site is usually reachable under more than one (hosting plus own domain).
+     */
+    origin?: string | string[];
+    /** IANA zone the day boundary follows. Functions run in UTC; default "UTC". */
+    timeZone?: string;
+    /** How long a visitor key stays the same. Default "day". */
+    rotate?: "day" | "month";
+    /** Optional salt; see the note above. */
+    secret?: string;
+    /**
+     * Days after which a row may be removed — written as `expires`.
+     *
+     * The FIELD is all this does. Deleting is a Firestore TTL policy on that
+     * field, switched on once per collection outside the code; without it the
+     * timestamp is documentation and nothing else. Say a retention period in a
+     * privacy notice only once the policy is on.
+     */
+    retentionDays?: number;
+    /** Default "visits". */
+    collection?: string;
+    /** Named Firestore database. */
+    databaseId?: string;
+}
+export interface VisitResult {
+    counted: boolean;
+    day: string;
+}
+/**
+ * The day as YYYY-MM-DD in the given zone.
+ *
+ * "sv-SE" is the shortest way to an ISO-shaped date: `toISOString()` would be
+ * UTC, and building it by hand from parts is where off-by-one bugs live.
+ */
+export declare function visitDay(now: Date, timeZone: string): string;
+/** The stretch of time a visitor key stays the same. */
+export declare function visitPeriod(day: string, rotate: "day" | "month"): string;
+/** The technical key — short enough to read, long enough not to collide. */
+export declare function visitorKey(period: string, ip: string, userAgent: string, secret?: string): string;
+/** Unknown values are dropped, never guessed and never stored raw. */
+export declare function cleanDevice(value: unknown): VisitDevice | undefined;
+/** A host, nothing else — no path, no query, no room for someone else's data. */
+export declare function cleanReferrer(value: unknown): string | undefined;
+export declare function isBot(userAgent: string): boolean;
+export interface BrowserInfo {
+    /** Family as the user would name it, or "other". */
+    browser: string;
+    /** MAJOR version only. The minor and patch parts identify, they do not inform. */
+    version?: string;
+}
+/**
+ * Browser family and major version.
+ *
+ * ORDER IS THE WHOLE TRICK, because these strings quote each other: Edge says
+ * Edg AND Chrome AND Safari, Chrome says Chrome AND Safari. So the most
+ * specific claim wins, and Safari is asked last. On iOS every engine is
+ * Safari's, but the browsers name themselves (CriOS, FxiOS) — reported as what
+ * the user sees, since that is what the question is about.
+ *
+ * Unclassified traffic becomes "other" rather than nothing: an unreadable
+ * agent is a fact worth seeing, missing data is a different fact.
+ */
+export declare function browserOf(userAgent: string): BrowserInfo;
+/**
+ * Operating system family, never a version.
+ *
+ * Android carries "Linux" in its agent and an iPad in desktop mode calls
+ * itself a Macintosh — so the order matters here too, and the iPad stays
+ * wrong. That is a limit of the source, not something to guess around.
+ */
+export declare function osOf(userAgent: string): string;
+/** No list means no restriction; an empty match means this call does not count. */
+export declare function originAllowed(origin: unknown, allowed?: string | string[]): boolean;
+/** First entry of x-forwarded-for; the rest are proxies. */
+export declare function clientIp(headers: Record<string, unknown>): string | undefined;
+/**
+ * Count one visit — or recognise that this visitor was already counted today.
+ *
+ * Never throws for the ordinary "does not count" cases (wrong origin, bot, no
+ * address, already seen): the caller is a fire-and-forget call from a page
+ * that must not care.
+ */
+export declare function countVisit(request: CallableRequest, visit?: VisitInput, options?: CountVisitOptions): Promise<VisitResult>;
+//# sourceMappingURL=visits.d.ts.map

package/dist/visits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visits.d.ts","sourceRoot":"","sources":["../src/visits.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;IACzB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAWD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAExE;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,SAAK,GACV,MAAM,CAKR;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAInE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAIhE;AAED,wBAAgB,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAgBxD;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ9C;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAC3B,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAC1B,OAAO,CAIT;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,SAAS,CAM7E;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,eAAe,EACxB,KAAK,GAAE,UAAe,EACtB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,WAAW,CAAC,CAqDtB"}

package/dist/visits.js

@@ -0,0 +1,147 @@
+import { getDb } from "./firestore.js";
+import { FieldValue, Timestamp } from "firebase-admin/firestore";
+import { createHash } from "node:crypto";
+//#region src/visits.ts
+var DEVICES = [
+	"phone",
+	"tablet",
+	"desktop"
+];
+/** Deliberately short: this keeps out the loudest noise, it is not a bot list. */
+var BOTS = /bot|crawl|spider|slurp|preview|monitor|headless|lighthouse|curl|wget/i;
+/** Firestore ALREADY_EXISTS — a gRPC status code, not an HTTP one. */
+var ALREADY_EXISTS = 6;
+/**
+* The day as YYYY-MM-DD in the given zone.
+*
+* "sv-SE" is the shortest way to an ISO-shaped date: `toISOString()` would be
+* UTC, and building it by hand from parts is where off-by-one bugs live.
+*/
+function visitDay(now, timeZone) {
+	return new Intl.DateTimeFormat("sv-SE", { timeZone }).format(now);
+}
+/** The stretch of time a visitor key stays the same. */
+function visitPeriod(day, rotate) {
+	return rotate === "month" ? day.slice(0, 7) : day;
+}
+/** The technical key — short enough to read, long enough not to collide. */
+function visitorKey(period, ip, userAgent, secret = "") {
+	return createHash("sha256").update(`${secret}|${period}|${ip}|${userAgent}`).digest("hex").slice(0, 16);
+}
+/** Unknown values are dropped, never guessed and never stored raw. */
+function cleanDevice(value) {
+	return typeof value === "string" && DEVICES.includes(value) ? value : void 0;
+}
+/** A host, nothing else — no path, no query, no room for someone else's data. */
+function cleanReferrer(value) {
+	if (typeof value !== "string") return void 0;
+	const host = value.trim().toLowerCase();
+	return /^[a-z0-9.\-:]{1,60}$/.test(host) ? host : void 0;
+}
+function isBot(userAgent) {
+	return BOTS.test(userAgent);
+}
+/**
+* Browser family and major version.
+*
+* ORDER IS THE WHOLE TRICK, because these strings quote each other: Edge says
+* Edg AND Chrome AND Safari, Chrome says Chrome AND Safari. So the most
+* specific claim wins, and Safari is asked last. On iOS every engine is
+* Safari's, but the browsers name themselves (CriOS, FxiOS) — reported as what
+* the user sees, since that is what the question is about.
+*
+* Unclassified traffic becomes "other" rather than nothing: an unreadable
+* agent is a fact worth seeing, missing data is a different fact.
+*/
+function browserOf(userAgent) {
+	for (const [browser, pattern] of [
+		["Edge", /Edg(?:iOS|A)?\/(\d+)/],
+		["Opera", /OPR\/(\d+)/],
+		["Samsung Internet", /SamsungBrowser\/(\d+)/],
+		["Chrome", /CriOS\/(\d+)/],
+		["Firefox", /FxiOS\/(\d+)/],
+		["Firefox", /Firefox\/(\d+)/],
+		["Chrome", /Chrome\/(\d+)/],
+		["Safari", /Version\/(\d+)[\d.]*\s+(?:Mobile\/\S+\s+)?Safari/]
+	]) {
+		const hit = pattern.exec(userAgent);
+		if (hit) return {
+			browser,
+			version: hit[1]
+		};
+	}
+	return { browser: "other" };
+}
+/**
+* Operating system family, never a version.
+*
+* Android carries "Linux" in its agent and an iPad in desktop mode calls
+* itself a Macintosh — so the order matters here too, and the iPad stays
+* wrong. That is a limit of the source, not something to guess around.
+*/
+function osOf(userAgent) {
+	if (/iPhone|iPad|iPod/.test(userAgent)) return "iOS";
+	if (/Android/.test(userAgent)) return "Android";
+	if (/CrOS/.test(userAgent)) return "ChromeOS";
+	if (/Windows/.test(userAgent)) return "Windows";
+	if (/Macintosh|Mac OS X/.test(userAgent)) return "macOS";
+	if (/Linux/.test(userAgent)) return "Linux";
+	return "other";
+}
+/** No list means no restriction; an empty match means this call does not count. */
+function originAllowed(origin, allowed) {
+	if (!allowed) return true;
+	return typeof origin === "string" && (Array.isArray(allowed) ? allowed : [allowed]).includes(origin);
+}
+/** First entry of x-forwarded-for; the rest are proxies. */
+function clientIp(headers) {
+	const raw = headers["x-forwarded-for"];
+	const value = Array.isArray(raw) ? raw[0] : raw;
+	if (typeof value !== "string") return void 0;
+	return value.split(",")[0]?.trim() || void 0;
+}
+/**
+* Count one visit — or recognise that this visitor was already counted today.
+*
+* Never throws for the ordinary "does not count" cases (wrong origin, bot, no
+* address, already seen): the caller is a fire-and-forget call from a page
+* that must not care.
+*/
+async function countVisit(request, visit = {}, options = {}) {
+	const headers = request.rawRequest?.headers ?? {};
+	const day = visitDay(/* @__PURE__ */ new Date(), options.timeZone ?? "UTC");
+	const skip = {
+		counted: false,
+		day
+	};
+	if (!originAllowed(headers.origin, options.origin)) return skip;
+	const userAgent = typeof headers["user-agent"] === "string" ? headers["user-agent"] : "";
+	if (!userAgent || isBot(userAgent)) return skip;
+	const ip = clientIp(headers);
+	if (!ip) return skip;
+	const { browser, version } = browserOf(userAgent);
+	const visitor = visitorKey(visitPeriod(day, options.rotate ?? "day"), ip, userAgent, options.secret);
+	try {
+		await getDb(options.databaseId).collection(options.collection ?? "visits").doc(`${day}_${visitor}`).create({
+			day,
+			visitor,
+			at: FieldValue.serverTimestamp(),
+			device: cleanDevice(visit.device),
+			standalone: visit.standalone === true,
+			referrer: cleanReferrer(visit.referrer),
+			browser,
+			browserVersion: version,
+			os: osOf(userAgent),
+			expires: options.retentionDays ? Timestamp.fromMillis(Date.now() + options.retentionDays * 864e5) : void 0
+		});
+		return {
+			counted: true,
+			day
+		};
+	} catch (e) {
+		if (e?.code === ALREADY_EXISTS) return skip;
+		throw e;
+	}
+}
+//#endregion
+export { browserOf, cleanDevice, cleanReferrer, clientIp, countVisit, isBot, originAllowed, osOf, visitDay, visitPeriod, visitorKey };

package/dist/visits.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=visits.spec.d.ts.map

package/dist/visits.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visits.spec.d.ts","sourceRoot":"","sources":["../src/visits.spec.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",
@@ -17,13 +17,12 @@
     "README.md",
     "LICENSE"
   ],
-  "dependencies": {
-    "firebase-admin": "^12.6.0",
-    "firebase-functions": "^6.0.0"
+  "engines": {
+    "node": "22"
   },
   "peerDependencies": {
-    "firebase-admin": "^12.6.0",
-    "firebase-functions": "^6.0.0"
+    "firebase-admin": ">=12.6.0 <15",
+    "firebase-functions": ">=6 <8"
   },
   "keywords": [
     "pd",
@@ -33,12 +32,16 @@
     "functions",
     "backend"
   ],
+  "devDependencies": {
+    "firebase-admin": "^14.3.0",
+    "firebase-functions": "^7.3.2"
+  },
   "scripts": {
     "build": "vite build",
     "clean": "rm -rf dist",
     "clean:all": "rm -rf dist node_modules pnpm-lock.yaml",
-    "lint": "eslint --ext .ts src --ignore-path ../../.eslintignore && prettier \"**/*.ts\" --check --ignore-path ../../.eslintignore",
-    "format": "eslint --ext .ts src --fix --ignore-path ../../.eslintignore && prettier \"**/*.ts\" --write --ignore-path ../../.eslintignore",
+    "lint": "eslint src && prettier \"**/*.ts\" --check --ignore-path ../../.eslintignore",
+    "format": "eslint src --fix && prettier \"**/*.ts\" --write --ignore-path ../../.eslintignore",
     "check": "pnpm run lint && pnpm run build",
     "test": "vitest run"
   }