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

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

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