@progressive-development/pd-provider-firebase-functions 1.3.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.js

@@ -1,105 +1,147 @@
-import { createHash } from 'node:crypto';
-import { Timestamp, FieldValue } from 'firebase-admin/firestore';
-import { getDb } from './firestore.js';
-
-const DEVICES = ["phone", "tablet", "desktop"];
-const BOTS = /bot|crawl|spider|slurp|preview|monitor|headless|lighthouse|curl|wget/i;
-const ALREADY_EXISTS = 6;
+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);
+	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;
+	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);
+	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;
+	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;
+	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);
+	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) {
-  const rules = [
-    ["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/]
-  ];
-  for (const [browser, pattern] of rules) {
-    const hit = pattern.exec(userAgent);
-    if (hit) return { browser, version: hit[1] };
-  }
-  return { browser: "other" };
+	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";
+	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;
-  const list = Array.isArray(allowed) ? allowed : [allowed];
-  return typeof origin === "string" && list.includes(origin);
+	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;
-  const first = value.split(",")[0]?.trim();
-  return first || void 0;
+	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 period = visitPeriod(day, options.rotate ?? "day");
-  const visitor = visitorKey(period, ip, userAgent, options.secret);
-  try {
-    await getDb(options.databaseId).collection(options.collection ?? "visits").doc(`${day}_${visitor}`).create({
-      day,
-      visitor,
-      at: FieldValue.serverTimestamp(),
-      // Missing is missing: getDb ignores undefined, so an absent value
-      // leaves no empty field behind.
-      device: cleanDevice(visit.device),
-      standalone: visit.standalone === true,
-      referrer: cleanReferrer(visit.referrer),
-      // Read from the agent the server already has — the client sends
-      // nothing for these. Family and MAJOR version only; the full string
-      // stays where it cannot be read back, in the key.
-      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;
-  }
+	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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "1.3.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"
   }