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

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 };

package/dist/mail.js

@@ -1,42 +1,63 @@
-import { Timestamp } from 'firebase-admin/firestore';
-import { getDb } from './firestore.js';
-import { ValidationError } from './errors.js';
-
-const DEFAULT_MAIL_COLLECTION = "mail";
+import { ValidationError } from "./errors.js";
+import { getDb } from "./firestore.js";
+import { Timestamp } from "firebase-admin/firestore";
+//#region src/mail.ts
+var DEFAULT_MAIL_COLLECTION = "mail";
+/**
+* Write a mail document for the Firebase mail extension to send.
+*
+* Throws on failure — the calling app decides whether a mail error aborts
+* its flow or is just logged.
+*
+* @param mail - The mail data; app-specific extra fields are stored as-is
+* @param collection - Mail collection name (default: "mail")
+* @param databaseId - Optional named database
+* @returns The created mail document ID
+* @throws ValidationError if `to` is missing or neither template nor message is set
+*/
 async function addMailForSend(mail, collection = DEFAULT_MAIL_COLLECTION, databaseId) {
-  if (!mail.to) {
-    throw new ValidationError("Mail requires a recipient (to)");
-  }
-  if (!mail.template && !mail.message) {
-    throw new ValidationError("Mail requires a template or a message");
-  }
-  const db = getDb(databaseId);
-  const docRef = await db.collection(collection).add({
-    ...mail,
-    creation: Timestamp.now()
-  });
-  return docRef.id;
+	if (!mail.to) throw new ValidationError("Mail requires a recipient (to)");
+	if (!mail.template && !mail.message) throw new ValidationError("Mail requires a template or a message");
+	return (await getDb(databaseId).collection(collection).add({
+		...mail,
+		creation: Timestamp.now()
+	})).id;
 }
+/**
+* Get a single mail document by ID (e.g. to inspect delivery state).
+*
+* @param mailId - The mail document ID
+* @param collection - Mail collection name (default: "mail")
+* @param databaseId - Optional named database
+* @returns The stored mail or null if not found
+*/
 async function getMailById(mailId, collection = DEFAULT_MAIL_COLLECTION, databaseId) {
-  const db = getDb(databaseId);
-  const doc = await db.collection(collection).doc(mailId).get();
-  if (!doc.exists) {
-    return null;
-  }
-  return {
-    id: doc.id,
-    ...doc.data()
-  };
+	const doc = await getDb(databaseId).collection(collection).doc(mailId).get();
+	if (!doc.exists) return null;
+	return {
+		id: doc.id,
+		...doc.data()
+	};
 }
+/**
+* List mail documents by an app-specific correlation field
+* (e.g. field "eventId").
+*
+* Deliberately without orderBy — no composite index requirement per queried
+* field; sorting is up to the caller.
+*
+* @param field - Field name to filter on
+* @param value - Value the field must equal
+* @param collection - Mail collection name (default: "mail")
+* @param limit - Maximum documents to return (default: 100)
+* @param databaseId - Optional named database
+* @returns Array of stored mails
+*/
 async function getMailsByField(field, value, collection = DEFAULT_MAIL_COLLECTION, limit = 100, databaseId) {
-  const db = getDb(databaseId);
-  const snapshot = await db.collection(collection).where(field, "==", value).limit(limit).get();
-  return snapshot.docs.map(
-    (doc) => ({
-      id: doc.id,
-      ...doc.data()
-    })
-  );
+	return (await getDb(databaseId).collection(collection).where(field, "==", value).limit(limit).get()).docs.map((doc) => ({
+		id: doc.id,
+		...doc.data()
+	}));
 }
-
+//#endregion
 export { addMailForSend, getMailById, getMailsByField };

package/dist/response.js

@@ -1,33 +1,42 @@
-import { StatusCode } from './types.js';
-import { AppError } from './errors.js';
-import { logger } from './logger.js';
-
+import { StatusCode } from "./types.js";
+import { AppError } from "./errors.js";
+import { logger } from "./logger.js";
+//#region src/response.ts
 function success(data) {
-  return { statusCode: StatusCode.OK, resultData: data };
+	return {
+		statusCode: StatusCode.OK,
+		resultData: data
+	};
 }
 function created(data) {
-  return { statusCode: StatusCode.CREATED, resultData: data };
+	return {
+		statusCode: StatusCode.CREATED,
+		resultData: data
+	};
 }
 function handleError(error) {
-  if (error instanceof AppError) {
-    if (error.statusCode >= 500) {
-      logger.error("App error", error);
-    } else {
-      logger.warn("Request error", {
-        code: error.code,
-        message: error.message
-      });
-    }
-    return {
-      statusCode: error.statusCode,
-      resultData: { error: error.message, code: error.code }
-    };
-  }
-  logger.error("Unexpected error", error);
-  return {
-    statusCode: StatusCode.INTERNAL_ERROR,
-    resultData: { error: "Internal server error", code: "INTERNAL_ERROR" }
-  };
+	if (error instanceof AppError) {
+		if (error.statusCode >= 500) logger.error("App error", error);
+		else logger.warn("Request error", {
+			code: error.code,
+			message: error.message
+		});
+		return {
+			statusCode: error.statusCode,
+			resultData: {
+				error: error.message,
+				code: error.code
+			}
+		};
+	}
+	logger.error("Unexpected error", error);
+	return {
+		statusCode: StatusCode.INTERNAL_ERROR,
+		resultData: {
+			error: "Internal server error",
+			code: "INTERNAL_ERROR"
+		}
+	};
 }
-
+//#endregion
 export { created, handleError, success };