@progressive-development/pd-provider-firebase-functions 1.3.0 → 1.4.0

package/dist/counter.js

@@ -1,20 +1,22 @@
-import { getDb } from './firestore.js';
-
-const COUNTERS_COLLECTION = "counters";
+import { getDb } from "./firestore.js";
+//#region src/counter.ts
+var COUNTERS_COLLECTION = "counters";
+/**
+* Get next counter value atomically
+* Uses Firestore transaction to prevent race conditions
+*/
 async function getNextCounter(counterName, databaseId) {
-  const db = getDb(databaseId);
-  const counterRef = db.collection(COUNTERS_COLLECTION).doc(counterName);
-  return db.runTransaction(async (transaction) => {
-    const doc = await transaction.get(counterRef);
-    const current = doc.exists ? doc.data()?.value ?? 0 : 0;
-    const next = current + 1;
-    transaction.set(
-      counterRef,
-      { value: next, updatedAt: /* @__PURE__ */ new Date() },
-      { merge: true }
-    );
-    return next;
-  });
+	const db = getDb(databaseId);
+	const counterRef = db.collection(COUNTERS_COLLECTION).doc(counterName);
+	return db.runTransaction(async (transaction) => {
+		const doc = await transaction.get(counterRef);
+		const next = (doc.exists ? doc.data()?.value ?? 0 : 0) + 1;
+		transaction.set(counterRef, {
+			value: next,
+			updatedAt: /* @__PURE__ */ new Date()
+		}, { merge: true });
+		return next;
+	});
 }
-
+//#endregion
 export { getNextCounter };

package/dist/errors.js

@@ -1,41 +1,42 @@
-const SC_EMAIL_ALREADY_USED = -160;
-class AppError extends Error {
-  constructor(message, code, statusCode) {
-    super(message);
-    this.code = code;
-    this.statusCode = statusCode;
-    this.name = this.constructor.name;
-  }
-}
-class ValidationError extends AppError {
-  constructor(message) {
-    super(message, "VALIDATION_ERROR", 400);
-  }
-}
-class UnauthorizedError extends AppError {
-  constructor(message = "Authentication required") {
-    super(message, "UNAUTHORIZED", 401);
-  }
-}
-class ForbiddenError extends AppError {
-  constructor(message = "Access denied") {
-    super(message, "FORBIDDEN", 403);
-  }
-}
-class NotFoundError extends AppError {
-  constructor(message) {
-    super(message, "NOT_FOUND", 404);
-  }
-}
-class ConflictError extends AppError {
-  constructor(message, code = "CONFLICT") {
-    super(message, code, 409);
-  }
-}
-class EmailAlreadyUsedError extends AppError {
-  constructor() {
-    super("Email already used", "EMAIL_ALREADY_USED", SC_EMAIL_ALREADY_USED);
-  }
-}
-
+//#region src/errors.ts
+var SC_EMAIL_ALREADY_USED = -160;
+var AppError = class extends Error {
+	constructor(message, code, statusCode) {
+		super(message);
+		this.code = code;
+		this.statusCode = statusCode;
+		this.name = this.constructor.name;
+	}
+};
+var ValidationError = class extends AppError {
+	constructor(message) {
+		super(message, "VALIDATION_ERROR", 400);
+	}
+};
+var UnauthorizedError = class extends AppError {
+	constructor(message = "Authentication required") {
+		super(message, "UNAUTHORIZED", 401);
+	}
+};
+var ForbiddenError = class extends AppError {
+	constructor(message = "Access denied") {
+		super(message, "FORBIDDEN", 403);
+	}
+};
+var NotFoundError = class extends AppError {
+	constructor(message) {
+		super(message, "NOT_FOUND", 404);
+	}
+};
+var ConflictError = class extends AppError {
+	constructor(message, code = "CONFLICT") {
+		super(message, code, 409);
+	}
+};
+var EmailAlreadyUsedError = class extends AppError {
+	constructor() {
+		super("Email already used", "EMAIL_ALREADY_USED", SC_EMAIL_ALREADY_USED);
+	}
+};
+//#endregion
 export { AppError, ConflictError, EmailAlreadyUsedError, ForbiddenError, NotFoundError, SC_EMAIL_ALREADY_USED, UnauthorizedError, ValidationError };

package/dist/firestore.js

@@ -1,14 +1,20 @@
-import { getFirestore } from 'firebase-admin/firestore';
-
-const dbCache = /* @__PURE__ */ new Map();
+import { getFirestore } from "firebase-admin/firestore";
+//#region src/firestore.ts
+var dbCache = /* @__PURE__ */ new Map();
+/**
+* Get Firestore instance (cached)
+*
+* Uses the default Firebase app - consumer must call initializeApp() first.
+* @param databaseId Optional named database
+*/
 function getDb(databaseId) {
-  const cacheKey = databaseId ?? "default";
-  if (!dbCache.has(cacheKey)) {
-    const db = databaseId ? getFirestore(databaseId) : getFirestore();
-    db.settings({ ignoreUndefinedProperties: true });
-    dbCache.set(cacheKey, db);
-  }
-  return dbCache.get(cacheKey);
+	const cacheKey = databaseId ?? "default";
+	if (!dbCache.has(cacheKey)) {
+		const db = databaseId ? getFirestore(databaseId) : getFirestore();
+		db.settings({ ignoreUndefinedProperties: true });
+		dbCache.set(cacheKey, db);
+	}
+	return dbCache.get(cacheKey);
 }
-
+//#endregion
 export { getDb };

package/dist/history.js

@@ -1,53 +1,82 @@
-import { Timestamp } from 'firebase-admin/firestore';
-import { getDb } from './firestore.js';
-import { ValidationError } from './errors.js';
-import { logger } from './logger.js';
-
-const HISTORY_COLLECTION = "_history";
-const HistoryKind = {
-  CREATED: "created",
-  UPDATED: "updated",
-  DELETED: "deleted",
-  RESTORED: "restored",
-  PROCESS: "process"
+import { ValidationError } from "./errors.js";
+import { logger } from "./logger.js";
+import { getDb } from "./firestore.js";
+import { Timestamp } from "firebase-admin/firestore";
+//#region src/history.ts
+var HISTORY_COLLECTION = "_history";
+/**
+* Core event categories — fixed in the helper. App-specific semantics go
+* into the free-form `action` field, NOT in here.
+*/
+var HistoryKind = {
+	CREATED: "created",
+	UPDATED: "updated",
+	DELETED: "deleted",
+	RESTORED: "restored",
+	PROCESS: "process"
 };
+/**
+* Write a history entry.
+*
+* Throws on failure — use recordHistory() at app write sites where a
+* history error must never fail the main operation.
+*
+* @param entry - The event data (at is set server-side)
+* @param databaseId - Optional named database
+* @returns The created history entry
+* @throws ValidationError if the object reference is incomplete
+*/
 async function addHistoryEntry(entry, databaseId) {
-  if (!entry.objectCollection || !entry.objectId || !entry.objectType) {
-    throw new ValidationError(
-      "History entry requires objectCollection, objectId and objectType"
-    );
-  }
-  const db = getDb(databaseId);
-  const entryData = {
-    ...entry,
-    at: Timestamp.now()
-  };
-  const docRef = await db.collection(HISTORY_COLLECTION).add(entryData);
-  return {
-    id: docRef.id,
-    ...entryData
-  };
+	if (!entry.objectCollection || !entry.objectId || !entry.objectType) throw new ValidationError("History entry requires objectCollection, objectId and objectType");
+	const db = getDb(databaseId);
+	const entryData = {
+		...entry,
+		at: Timestamp.now()
+	};
+	return {
+		id: (await db.collection(HISTORY_COLLECTION).add(entryData)).id,
+		...entryData
+	};
 }
+/**
+* Best-effort variant of addHistoryEntry for app write sites: catches ANY
+* error, logs it as a warning and returns null. The app's main operation
+* can never fail because of history recording.
+*
+* @param entry - The event data
+* @param databaseId - Optional named database
+* @returns The created history entry, or null if recording failed
+*/
 async function recordHistory(entry, databaseId) {
-  try {
-    return await addHistoryEntry(entry, databaseId);
-  } catch (error) {
-    logger.warn("recordHistory failed", {
-      error: error instanceof Error ? error.message : String(error),
-      objectCollection: entry.objectCollection,
-      objectId: entry.objectId,
-      kind: entry.kind
-    });
-    return null;
-  }
+	try {
+		return await addHistoryEntry(entry, databaseId);
+	} catch (error) {
+		logger.warn("recordHistory failed", {
+			error: error instanceof Error ? error.message : String(error),
+			objectCollection: entry.objectCollection,
+			objectId: entry.objectId,
+			kind: entry.kind
+		});
+		return null;
+	}
 }
+/**
+* List the history of an object, newest first.
+*
+* Requires a composite index in the consuming project:
+* objectCollection ASC, objectId ASC, at DESC on collection "_history".
+*
+* @param objectCollection - Collection of the object (e.g., "locations")
+* @param objectId - Document ID of the object
+* @param limit - Maximum entries to return (default: 100)
+* @param databaseId - Optional named database
+* @returns Array of history entries, newest first
+*/
 async function listHistory(objectCollection, objectId, limit = 100, databaseId) {
-  const db = getDb(databaseId);
-  const snapshot = await db.collection(HISTORY_COLLECTION).where("objectCollection", "==", objectCollection).where("objectId", "==", objectId).orderBy("at", "desc").limit(limit).get();
-  return snapshot.docs.map((doc) => ({
-    id: doc.id,
-    ...doc.data()
-  }));
+	return (await getDb(databaseId).collection(HISTORY_COLLECTION).where("objectCollection", "==", objectCollection).where("objectId", "==", objectId).orderBy("at", "desc").limit(limit).get()).docs.map((doc) => ({
+		id: doc.id,
+		...doc.data()
+	}));
 }
-
+//#endregion
 export { HistoryKind, addHistoryEntry, listHistory, recordHistory };

package/dist/import-templates.js

@@ -1,113 +1,109 @@
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { scriptLog, createScriptContext } from './script-helpers.js';
-
+import { createScriptContext, scriptLog } from "./script-helpers.js";
+import { existsSync, readFileSync, readdirSync } from "fs";
+//#region src/import-templates.ts
+/**
+* Reusable Mail Templates Import
+*
+* Imports mail templates from a templates directory into Firestore.
+* Each template consists of three files:
+*   - {name}.json          — metadata (name, subject)
+*   - {name}.html.hbs      — HTML template
+*   - {name}.txt.hbs       — Text template
+*/
 function findTemplates(templatesDir) {
-  const files = readdirSync(templatesDir);
-  const jsonFiles = files.filter(
-    (f) => f.endsWith(".json") && f !== "serviceAccountKey.json"
-  );
-  return jsonFiles.map((f) => f.replace(".json", ""));
+	return readdirSync(templatesDir).filter((f) => f.endsWith(".json") && f !== "serviceAccountKey.json").map((f) => f.replace(".json", ""));
 }
 function loadTemplate(templatesDir, name) {
-  const jsonPath = `${templatesDir}/${name}.json`;
-  const htmlPath = `${templatesDir}/${name}.html.hbs`;
-  const textPath = `${templatesDir}/${name}.txt.hbs`;
-  if (!existsSync(jsonPath)) {
-    scriptLog(`Metadata not found: ${jsonPath}`, "error");
-    return null;
-  }
-  if (!existsSync(htmlPath)) {
-    scriptLog(`HTML template not found: ${htmlPath}`, "error");
-    return null;
-  }
-  if (!existsSync(textPath)) {
-    scriptLog(`Text template not found: ${textPath}`, "error");
-    return null;
-  }
-  const metadata = JSON.parse(
-    readFileSync(jsonPath, "utf-8")
-  );
-  const html = readFileSync(htmlPath, "utf-8");
-  const text = readFileSync(textPath, "utf-8");
-  return { ...metadata, html, text };
+	const jsonPath = `${templatesDir}/${name}.json`;
+	const htmlPath = `${templatesDir}/${name}.html.hbs`;
+	const textPath = `${templatesDir}/${name}.txt.hbs`;
+	if (!existsSync(jsonPath)) {
+		scriptLog(`Metadata not found: ${jsonPath}`, "error");
+		return null;
+	}
+	if (!existsSync(htmlPath)) {
+		scriptLog(`HTML template not found: ${htmlPath}`, "error");
+		return null;
+	}
+	if (!existsSync(textPath)) {
+		scriptLog(`Text template not found: ${textPath}`, "error");
+		return null;
+	}
+	const metadata = JSON.parse(readFileSync(jsonPath, "utf-8"));
+	const html = readFileSync(htmlPath, "utf-8");
+	const text = readFileSync(textPath, "utf-8");
+	return {
+		...metadata,
+		html,
+		text
+	};
 }
+/**
+* Import mail templates into Firestore.
+*/
 async function runImportTemplates(config) {
-  const {
-    templatesDir,
-    serviceAccountPath,
-    databaseId,
-    collection = "emailTemplates",
-    templateFilter,
-    dryRun = false
-  } = config;
-  if (!existsSync(templatesDir)) {
-    scriptLog(`Templates directory not found: ${templatesDir}`, "error");
-    process.exit(1);
-  }
-  const { db } = createScriptContext({
-    title: "Mail Templates Import",
-    serviceAccountPath,
-    databaseId,
-    dryRun
-  });
-  scriptLog(`Templates dir: ${templatesDir}`);
-  scriptLog(`Target collection: ${collection}`);
-  let templates = findTemplates(templatesDir);
-  if (templateFilter) {
-    templates = templates.filter((t) => t === templateFilter);
-    if (templates.length === 0) {
-      scriptLog(`Template not found: ${templateFilter}`, "error");
-      process.exit(1);
-    }
-  }
-  scriptLog(`Found ${templates.length} template(s): ${templates.join(", ")}`);
-  console.log("");
-  let successCount = 0;
-  let errorCount = 0;
-  for (const templateName of templates) {
-    const template = loadTemplate(templatesDir, templateName);
-    if (!template) {
-      errorCount++;
-      continue;
-    }
-    const docId = `${templateName}Id`;
-    console.log(`
-  ${templateName}`);
-    console.log(`   Document ID: ${docId}`);
-    console.log(`   Subject: ${template.subject}`);
-    console.log(`   HTML: ${template.html.length} chars`);
-    console.log(`   Text: ${template.text.length} chars`);
-    if (!dryRun) {
-      try {
-        await db.collection(collection).doc(docId).set({
-          name: template.name,
-          subject: template.subject,
-          html: template.html,
-          text: template.text,
-          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-        });
-        scriptLog(`Imported: ${templateName} -> ${docId}`, "success");
-        successCount++;
-      } catch (error) {
-        scriptLog(`Failed to import ${templateName}: ${error}`, "error");
-        errorCount++;
-      }
-    } else {
-      scriptLog(`Would import: ${templateName} -> ${docId}`, "info");
-      successCount++;
-    }
-  }
-  console.log("\n" + "-".repeat(50));
-  console.log(`
-Summary:`);
-  console.log(`   Success: ${successCount}`);
-  console.log(`   Errors:  ${errorCount}`);
-  if (dryRun) {
-    console.log(`
-   Run without --dry-run to apply changes.
-`);
-  }
-  process.exit(errorCount > 0 ? 1 : 0);
+	const { templatesDir, serviceAccountPath, databaseId, collection = "emailTemplates", templateFilter, dryRun = false } = config;
+	if (!existsSync(templatesDir)) {
+		scriptLog(`Templates directory not found: ${templatesDir}`, "error");
+		process.exit(1);
+	}
+	const { db } = createScriptContext({
+		title: "Mail Templates Import",
+		serviceAccountPath,
+		databaseId,
+		dryRun
+	});
+	scriptLog(`Templates dir: ${templatesDir}`);
+	scriptLog(`Target collection: ${collection}`);
+	let templates = findTemplates(templatesDir);
+	if (templateFilter) {
+		templates = templates.filter((t) => t === templateFilter);
+		if (templates.length === 0) {
+			scriptLog(`Template not found: ${templateFilter}`, "error");
+			process.exit(1);
+		}
+	}
+	scriptLog(`Found ${templates.length} template(s): ${templates.join(", ")}`);
+	console.log("");
+	let successCount = 0;
+	let errorCount = 0;
+	for (const templateName of templates) {
+		const template = loadTemplate(templatesDir, templateName);
+		if (!template) {
+			errorCount++;
+			continue;
+		}
+		const docId = `${templateName}Id`;
+		console.log(`\n  ${templateName}`);
+		console.log(`   Document ID: ${docId}`);
+		console.log(`   Subject: ${template.subject}`);
+		console.log(`   HTML: ${template.html.length} chars`);
+		console.log(`   Text: ${template.text.length} chars`);
+		if (!dryRun) try {
+			await db.collection(collection).doc(docId).set({
+				name: template.name,
+				subject: template.subject,
+				html: template.html,
+				text: template.text,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			});
+			scriptLog(`Imported: ${templateName} -> ${docId}`, "success");
+			successCount++;
+		} catch (error) {
+			scriptLog(`Failed to import ${templateName}: ${error}`, "error");
+			errorCount++;
+		}
+		else {
+			scriptLog(`Would import: ${templateName} -> ${docId}`, "info");
+			successCount++;
+		}
+	}
+	console.log("\n" + "-".repeat(50));
+	console.log(`\nSummary:`);
+	console.log(`   Success: ${successCount}`);
+	console.log(`   Errors:  ${errorCount}`);
+	if (dryRun) console.log(`\n   Run without --dry-run to apply changes.\n`);
+	process.exit(errorCount > 0 ? 1 : 0);
 }
-
+//#endregion
 export { runImportTemplates };

package/dist/index.js

@@ -1,15 +1,16 @@
-export { StatusCode } from './types.js';
-export { AppError, ConflictError, EmailAlreadyUsedError, ForbiddenError, NotFoundError, SC_EMAIL_ALREADY_USED, UnauthorizedError, ValidationError } from './errors.js';
-export { requireAuth, requireClaims, requireOwnership } from './auth.js';
-export { created, handleError, success } from './response.js';
-export { getDb } from './firestore.js';
-export { getNextCounter } from './counter.js';
-export { countVisit } from './visits.js';
-export { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash } from './trash.js';
-export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth } from './auth-trash.js';
-export { computeChanges } from './changes.js';
-export { HistoryKind, addHistoryEntry, listHistory, recordHistory } from './history.js';
-export { addMailForSend, getMailById, getMailsByField } from './mail.js';
-export { logger } from './logger.js';
-export { createScriptContext, initFirebaseAdmin, scriptLog } from './script-helpers.js';
-export { runImportTemplates } from './import-templates.js';
+import { StatusCode } from "./types.js";
+import { AppError, ConflictError, EmailAlreadyUsedError, ForbiddenError, NotFoundError, SC_EMAIL_ALREADY_USED, UnauthorizedError, ValidationError } from "./errors.js";
+import { logger } from "./logger.js";
+import { requireAuth, requireClaims, requireOwnership } from "./auth.js";
+import { created, handleError, success } from "./response.js";
+import { getDb } from "./firestore.js";
+import { getNextCounter } from "./counter.js";
+import { countVisit } from "./visits.js";
+import { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash } from "./trash.js";
+import { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth } from "./auth-trash.js";
+import { computeChanges } from "./changes.js";
+import { HistoryKind, addHistoryEntry, listHistory, recordHistory } from "./history.js";
+import { addMailForSend, getMailById, getMailsByField } from "./mail.js";
+import { createScriptContext, initFirebaseAdmin, scriptLog } from "./script-helpers.js";
+import { runImportTemplates } from "./import-templates.js";
+export { AppError, ConflictError, EmailAlreadyUsedError, ForbiddenError, HistoryKind, NotFoundError, SC_EMAIL_ALREADY_USED, StatusCode, UnauthorizedError, ValidationError, addHistoryEntry, addMailForSend, computeChanges, countVisit, createScriptContext, created, getDb, getMailById, getMailsByField, getNextCounter, getTrashItem, handleError, initFirebaseAdmin, listHistory, listTrash, logger, moveToTrash, moveToTrashWithAuth, permanentDelete, permanentDeleteWithAuth, recordHistory, requireAuth, requireClaims, requireOwnership, restoreFromTrash, restoreFromTrashWithAuth, runImportTemplates, scriptLog, success };

package/dist/logger.js

@@ -1,10 +1,13 @@
-import * as functions from 'firebase-functions/logger';
-
-const logger = {
-  debug: (msg, data) => functions.debug(msg, data),
-  info: (msg, data) => functions.info(msg, data),
-  warn: (msg, data) => functions.warn(msg, data),
-  error: (msg, error, data) => functions.error(msg, { error, ...data })
+import * as functions from "firebase-functions/logger";
+//#region src/logger.ts
+var logger = {
+	debug: (msg, data) => functions.debug(msg, data),
+	info: (msg, data) => functions.info(msg, data),
+	warn: (msg, data) => functions.warn(msg, data),
+	error: (msg, error, data) => functions.error(msg, {
+		error,
+		...data
+	})
 };
-
+//#endregion
 export { logger };