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

package/dist/auth-trash.js

@@ -1,116 +1,127 @@
-import { getAuth } from 'firebase-admin/auth';
-import { moveToTrash, getTrashItem, permanentDelete, restoreFromTrash } from './trash.js';
-import { NotFoundError } from './errors.js';
-import { logger } from './logger.js';
-
+import { NotFoundError } from "./errors.js";
+import { logger } from "./logger.js";
+import { getTrashItem, moveToTrash, permanentDelete, restoreFromTrash } from "./trash.js";
+import { getAuth } from "firebase-admin/auth";
+//#region src/auth-trash.ts
+/**
+* Auth-aware Trash Functions
+*
+* Extends the generic trash service with Firebase Auth user handling.
+* Use these when the trashed document is linked to an Auth user.
+*/
+/**
+* Extract Auth UID from trash item based on options.
+*/
 function getAuthUidFromTrashItem(trashItem, options) {
-  const source = options?.authUidSource ?? "documentId";
-  if (source === "documentId") {
-    return trashItem.originalId;
-  }
-  const data = trashItem.data;
-  const uid = data[source];
-  if (typeof uid !== "string" || !uid) {
-    throw new Error(
-      `Auth UID field '${source}' not found or empty in trash item data`
-    );
-  }
-  return uid;
+	const source = options?.authUidSource ?? "documentId";
+	if (source === "documentId") return trashItem.originalId;
+	const uid = trashItem.data[source];
+	if (typeof uid !== "string" || !uid) throw new Error(`Auth UID field '${source}' not found or empty in trash item data`);
+	return uid;
 }
+/**
+* Move document to trash AND disable the associated Auth user.
+*
+* Order of operations:
+* 1. Disable Auth user (if user doesn't exist, continue anyway)
+* 2. Move document to trash
+*
+* @param collection - The collection path
+* @param documentId - The document ID to trash
+* @param deletedBy - UID of the user performing the deletion
+* @param objectType - Type identifier for filtering
+* @param options - Auth and database options
+* @returns The created trash item
+*/
 async function moveToTrashWithAuth(collection, documentId, deletedBy, objectType, options) {
-  const authUid = options?.authUidSource === "documentId" || !options?.authUidSource ? documentId : documentId;
-  logger.info("Disabling Auth user before trash", {
-    authUid,
-    collection,
-    documentId
-  });
-  try {
-    await getAuth().updateUser(authUid, { disabled: true });
-    logger.info("Auth user disabled", { authUid });
-  } catch (error) {
-    const authError = error;
-    if (authError.code === "auth/user-not-found") {
-      logger.info("Auth user not found, continuing with trash operation", {
-        authUid
-      });
-    } else {
-      throw error;
-    }
-  }
-  const trashItem = await moveToTrash(
-    collection,
-    documentId,
-    deletedBy,
-    objectType,
-    options?.databaseId
-  );
-  logger.info("Document moved to trash with Auth disabled", {
-    trashItemId: trashItem.id,
-    authUid
-  });
-  return trashItem;
+	const authUid = options?.authUidSource === "documentId" || !options?.authUidSource ? documentId : documentId;
+	logger.info("Disabling Auth user before trash", {
+		authUid,
+		collection,
+		documentId
+	});
+	try {
+		await getAuth().updateUser(authUid, { disabled: true });
+		logger.info("Auth user disabled", { authUid });
+	} catch (error) {
+		if (error.code === "auth/user-not-found") logger.info("Auth user not found, continuing with trash operation", { authUid });
+		else throw error;
+	}
+	const trashItem = await moveToTrash(collection, documentId, deletedBy, objectType, options?.databaseId);
+	logger.info("Document moved to trash with Auth disabled", {
+		trashItemId: trashItem.id,
+		authUid
+	});
+	return trashItem;
 }
+/**
+* Restore document from trash AND re-enable the Auth user.
+*
+* Order of operations:
+* 1. Get trash item to find Auth UID
+* 2. Restore document from trash
+* 3. Re-enable Auth user (if user doesn't exist, log warning)
+*
+* @param trashItemId - The trash document ID
+* @param options - Auth and database options
+*/
 async function restoreFromTrashWithAuth(trashItemId, options) {
-  const trashItem = await getTrashItem(trashItemId, options?.databaseId);
-  if (!trashItem) {
-    throw new NotFoundError(`Trash item ${trashItemId} not found`);
-  }
-  const authUid = getAuthUidFromTrashItem(trashItem, options);
-  logger.info("Restoring from trash with Auth re-enable", {
-    trashItemId,
-    authUid,
-    originalCollection: trashItem.originalCollection
-  });
-  await restoreFromTrash(trashItemId, options?.databaseId);
-  try {
-    await getAuth().updateUser(authUid, { disabled: false });
-    logger.info("Document restored and Auth user re-enabled", {
-      trashItemId,
-      authUid
-    });
-  } catch (error) {
-    const authError = error;
-    if (authError.code === "auth/user-not-found") {
-      logger.warn(
-        "Document restored but Auth user not found - manual Auth user creation required",
-        {
-          trashItemId,
-          authUid
-        }
-      );
-    } else {
-      throw error;
-    }
-  }
+	const trashItem = await getTrashItem(trashItemId, options?.databaseId);
+	if (!trashItem) throw new NotFoundError(`Trash item ${trashItemId} not found`);
+	const authUid = getAuthUidFromTrashItem(trashItem, options);
+	logger.info("Restoring from trash with Auth re-enable", {
+		trashItemId,
+		authUid,
+		originalCollection: trashItem.originalCollection
+	});
+	await restoreFromTrash(trashItemId, options?.databaseId);
+	try {
+		await getAuth().updateUser(authUid, { disabled: false });
+		logger.info("Document restored and Auth user re-enabled", {
+			trashItemId,
+			authUid
+		});
+	} catch (error) {
+		if (error.code === "auth/user-not-found") logger.warn("Document restored but Auth user not found - manual Auth user creation required", {
+			trashItemId,
+			authUid
+		});
+		else throw error;
+	}
 }
+/**
+* Permanently delete from trash AND delete the Auth user.
+*
+* Order of operations:
+* 1. Get trash item to find Auth UID
+* 2. Delete from trash
+* 3. Delete Auth user (ignore if user doesn't exist)
+*
+* @param trashItemId - The trash document ID
+* @param options - Auth and database options
+*/
 async function permanentDeleteWithAuth(trashItemId, options) {
-  const trashItem = await getTrashItem(trashItemId, options?.databaseId);
-  if (!trashItem) {
-    throw new NotFoundError(`Trash item ${trashItemId} not found`);
-  }
-  const authUid = getAuthUidFromTrashItem(trashItem, options);
-  logger.info("Permanently deleting with Auth user deletion", {
-    trashItemId,
-    authUid
-  });
-  await permanentDelete(trashItemId, options?.databaseId);
-  try {
-    await getAuth().deleteUser(authUid);
-    logger.info("Trash item and Auth user permanently deleted", {
-      trashItemId,
-      authUid
-    });
-  } catch (error) {
-    const authError = error;
-    if (authError.code === "auth/user-not-found") {
-      logger.info("Auth user not found, trash item deleted", {
-        trashItemId,
-        authUid
-      });
-    } else {
-      throw error;
-    }
-  }
+	const trashItem = await getTrashItem(trashItemId, options?.databaseId);
+	if (!trashItem) throw new NotFoundError(`Trash item ${trashItemId} not found`);
+	const authUid = getAuthUidFromTrashItem(trashItem, options);
+	logger.info("Permanently deleting with Auth user deletion", {
+		trashItemId,
+		authUid
+	});
+	await permanentDelete(trashItemId, options?.databaseId);
+	try {
+		await getAuth().deleteUser(authUid);
+		logger.info("Trash item and Auth user permanently deleted", {
+			trashItemId,
+			authUid
+		});
+	} catch (error) {
+		if (error.code === "auth/user-not-found") logger.info("Auth user not found, trash item deleted", {
+			trashItemId,
+			authUid
+		});
+		else throw error;
+	}
 }
-
+//#endregion
 export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth };

package/dist/auth.js

@@ -1,30 +1,37 @@
-import { UnauthorizedError, ForbiddenError } from './errors.js';
-import { logger } from './logger.js';
-
+import { ForbiddenError, UnauthorizedError } from "./errors.js";
+import { logger } from "./logger.js";
+//#region src/auth.ts
+/**
+* Require authenticated user
+*/
 function requireAuth(request) {
-  if (!request.auth) {
-    throw new UnauthorizedError();
-  }
-  return {
-    uid: request.auth.uid,
-    email: request.auth.token.email ?? null,
-    claims: request.auth.token
-  };
+	if (!request.auth) throw new UnauthorizedError();
+	return {
+		uid: request.auth.uid,
+		email: request.auth.token.email ?? null,
+		claims: request.auth.token
+	};
 }
+/**
+* Require specific role claims.
+* Supports Firebase standard format: { admin: true, developer: true }
+*/
 function requireClaims(request, allowedRoles) {
-  const auth = requireAuth(request);
-  const hasRole = allowedRoles.some((role) => auth.claims[role] === true);
-  if (!hasRole) {
-    throw new ForbiddenError();
-  }
-  return auth;
+	const auth = requireAuth(request);
+	if (!allowedRoles.some((role) => auth.claims[role] === true)) throw new ForbiddenError();
+	return auth;
 }
+/**
+* Ensure user can only access own resources
+*/
 function requireOwnership(auth, resourceOwnerId) {
-  const isAdmin = auth.claims.admin === true;
-  if (!isAdmin && auth.uid !== resourceOwnerId) {
-    logger.warn("Ownership violation", { uid: auth.uid, resourceOwnerId });
-    throw new ForbiddenError("Cannot access other user's resources");
-  }
+	if (!(auth.claims.admin === true) && auth.uid !== resourceOwnerId) {
+		logger.warn("Ownership violation", {
+			uid: auth.uid,
+			resourceOwnerId
+		});
+		throw new ForbiddenError("Cannot access other user's resources");
+	}
 }
-
+//#endregion
 export { requireAuth, requireClaims, requireOwnership };

package/dist/changes.js

@@ -1,69 +1,62 @@
+//#region src/changes.ts
 function hasIsEqual(value) {
-  return typeof value === "object" && value !== null && typeof value.isEqual === "function";
+	return typeof value === "object" && value !== null && typeof value.isEqual === "function";
 }
+/** undefined, null and missing keys all count as "not set" and equal. */
 function isUnset(value) {
-  return value === void 0 || value === null;
+	return value === void 0 || value === null;
 }
 function isEqualValue(a, b) {
-  if (isUnset(a) && isUnset(b)) {
-    return true;
-  }
-  if (isUnset(a) || isUnset(b)) {
-    return false;
-  }
-  if (a === b) {
-    return true;
-  }
-  if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) {
-    return true;
-  }
-  if (hasIsEqual(a) && hasIsEqual(b)) {
-    try {
-      return a.isEqual(b);
-    } catch {
-      return false;
-    }
-  }
-  if (hasIsEqual(a) || hasIsEqual(b)) {
-    return false;
-  }
-  if (a instanceof Date && b instanceof Date) {
-    return a.getTime() === b.getTime();
-  }
-  if (Array.isArray(a) && Array.isArray(b)) {
-    return a.length === b.length && a.every((item, i) => isEqualValue(item, b[i]));
-  }
-  if (Array.isArray(a) || Array.isArray(b)) {
-    return false;
-  }
-  if (typeof a === "object" && typeof b === "object") {
-    const aObj = a;
-    const bObj = b;
-    const keys = /* @__PURE__ */ new Set([...Object.keys(aObj), ...Object.keys(bObj)]);
-    for (const key of keys) {
-      if (!isEqualValue(aObj[key], bObj[key])) {
-        return false;
-      }
-    }
-    return true;
-  }
-  return false;
+	if (isUnset(a) && isUnset(b)) return true;
+	if (isUnset(a) || isUnset(b)) return false;
+	if (a === b) return true;
+	if (typeof a === "number" && typeof b === "number" && Number.isNaN(a) && Number.isNaN(b)) return true;
+	if (hasIsEqual(a) && hasIsEqual(b)) try {
+		return a.isEqual(b);
+	} catch {
+		return false;
+	}
+	if (hasIsEqual(a) || hasIsEqual(b)) return false;
+	if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, i) => isEqualValue(item, b[i]));
+	if (Array.isArray(a) || Array.isArray(b)) return false;
+	if (typeof a === "object" && typeof b === "object") {
+		const aObj = a;
+		const bObj = b;
+		const keys = /* @__PURE__ */ new Set([...Object.keys(aObj), ...Object.keys(bObj)]);
+		for (const key of keys) if (!isEqualValue(aObj[key], bObj[key])) return false;
+		return true;
+	}
+	return false;
 }
+/**
+* Compute which top-level fields changed between two object states.
+*
+* Values are compared deeply (nested objects, arrays), but changes are
+* reported per top-level field with the full old/new value. Firestore value
+* types are compared via their own isEqual(). undefined, null and missing
+* keys are treated as the same "not set" state.
+*
+* @param before - Previous state; undefined means "object did not exist yet"
+* @param after - New state
+* @param options - Optional ignore list for noisy fields (e.g. "lastEdit")
+* @returns The changed fields — or undefined if nothing changed, so
+*          "did anything change?" is a truthiness check on the result
+*/
 function computeChanges(before, after, options) {
-  const ignore = new Set(options?.ignoreFields ?? []);
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before ?? {}), ...Object.keys(after)]);
-  const changes = {};
-  for (const key of keys) {
-    if (ignore.has(key)) {
-      continue;
-    }
-    const oldValue = before?.[key];
-    const newValue = after[key];
-    if (!isEqualValue(oldValue, newValue)) {
-      changes[key] = { old: oldValue ?? null, new: newValue ?? null };
-    }
-  }
-  return Object.keys(changes).length > 0 ? changes : void 0;
+	const ignore = new Set(options?.ignoreFields ?? []);
+	const keys = /* @__PURE__ */ new Set([...Object.keys(before ?? {}), ...Object.keys(after)]);
+	const changes = {};
+	for (const key of keys) {
+		if (ignore.has(key)) continue;
+		const oldValue = before?.[key];
+		const newValue = after[key];
+		if (!isEqualValue(oldValue, newValue)) changes[key] = {
+			old: oldValue ?? null,
+			new: newValue ?? null
+		};
+	}
+	return Object.keys(changes).length > 0 ? changes : void 0;
 }
-
+//#endregion
 export { computeChanges };

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