@progressive-development/pd-provider-firebase-functions 0.3.0 → 0.3.2

package/dist/auth-trash.d.ts

@@ -0,0 +1,51 @@
+import { TrashItem } from './trash';
+export interface AuthTrashOptions {
+    /**
+     * How to determine the Auth UID from the document.
+     * - 'documentId': Use the document ID as Auth UID (default)
+     * - string: Use this field name from the document data
+     */
+    authUidSource?: "documentId" | string;
+    /** Optional named database */
+    databaseId?: string;
+}
+/**
+ * Move document to trash AND disable the associated Auth user.
+ *
+ * Order of operations:
+ * 1. Disable Auth user (if this fails, nothing else happens)
+ * 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
+ */
+export declare function moveToTrashWithAuth<T = unknown>(collection: string, documentId: string, deletedBy: string, objectType: string, options?: AuthTrashOptions): Promise<TrashItem<T>>;
+/**
+ * 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
+ *
+ * @param trashItemId - The trash document ID
+ * @param options - Auth and database options
+ */
+export declare function restoreFromTrashWithAuth(trashItemId: string, options?: AuthTrashOptions): Promise<void>;
+/**
+ * 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
+ *
+ * @param trashItemId - The trash document ID
+ * @param options - Auth and database options
+ */
+export declare function permanentDeleteWithAuth(trashItemId: string, options?: AuthTrashOptions): Promise<void>;
+//# sourceMappingURL=auth-trash.d.ts.map

package/dist/auth-trash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-trash.d.ts","sourceRoot":"","sources":["../src/auth-trash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAgE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAQvG,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEtC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAkCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA0BvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/auth-trash.js

@@ -0,0 +1,66 @@
+import { getAuth } from 'firebase-admin/auth';
+import { moveToTrash, getTrashItem, restoreFromTrash, permanentDelete } from './trash.js';
+import { NotFoundError } from './errors.js';
+import { logger } from './logger.js';
+
+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;
+}
+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 });
+  await getAuth().updateUser(authUid, { disabled: true });
+  logger.info("Auth user disabled", { authUid });
+  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;
+}
+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);
+  await getAuth().updateUser(authUid, { disabled: false });
+  logger.info("Document restored and Auth user re-enabled", { trashItemId, authUid });
+}
+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);
+  await getAuth().deleteUser(authUid);
+  logger.info("Trash item and Auth user permanently deleted", { trashItemId, authUid });
+}
+
+export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth };

package/dist/index.d.ts

@@ -5,5 +5,9 @@ export { requireAuth, requireClaims, requireOwnership } from './auth';
 export { success, created, handleError } from './response';
 export { getDb } from './firestore';
 export { getNextCounter } from './counter';
+export type { TrashItem } from './trash';
+export { moveToTrash, restoreFromTrash, permanentDelete, listTrash, getTrashItem } from './trash';
+export type { AuthTrashOptions } from './auth-trash';
+export { moveToTrashWithAuth, restoreFromTrashWithAuth, permanentDeleteWithAuth } from './auth-trash';
 export { logger } from './logger';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGvG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGvG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAGtE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG3D,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3C,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,eAAe,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGlG,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAGtG,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.js

@@ -4,4 +4,6 @@ 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 { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash } from './trash.js';
+export { moveToTrashWithAuth, permanentDeleteWithAuth, restoreFromTrashWithAuth } from './auth-trash.js';
 export { logger } from './logger.js';

package/dist/trash.d.ts

@@ -0,0 +1,77 @@
+import { Timestamp } from 'firebase-admin/firestore';
+/**
+ * Represents an item in the trash collection.
+ * Generic type T is the shape of the original document data.
+ */
+export interface TrashItem<T = unknown> {
+    /** Auto-generated trash document ID */
+    id: string;
+    /** Original document ID */
+    originalId: string;
+    /** Original collection path */
+    originalCollection: string;
+    /** Object type for filtering (e.g., "djRequest", "event") */
+    objectType: string;
+    /** When the item was deleted */
+    deletedAt: Timestamp;
+    /** UID of user who deleted */
+    deletedBy: string;
+    /** The original document data */
+    data: T;
+}
+/**
+ * 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 user performing the deletion
+ * @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
+ */
+export declare function moveToTrash<T = unknown>(collection: string, documentId: string, deletedBy: string, objectType: string, databaseId?: string): Promise<TrashItem<T>>;
+/**
+ * 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
+ */
+export declare function restoreFromTrash(trashItemId: string, databaseId?: string): Promise<void>;
+/**
+ * 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
+ */
+export declare function permanentDelete(trashItemId: string, databaseId?: string): Promise<void>;
+/**
+ * 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
+ */
+export declare function listTrash<T = unknown>(objectType?: string, limit?: number, databaseId?: string): Promise<TrashItem<T>[]>;
+/**
+ * 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
+ */
+export declare function getTrashItem<T = unknown>(trashItemId: string, databaseId?: string): Promise<TrashItem<T> | null>;
+//# sourceMappingURL=trash.d.ts.map

package/dist/trash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trash.d.ts","sourceRoot":"","sources":["../src/trash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAcrD;;;GAGG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,SAAS,EAAE,SAAS,CAAC;IACrB,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,IAAI,EAAE,CAAC,CAAC;CACT;AASD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAmCvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,MAAY,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAiBzB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,GAAG,OAAO,EAC5C,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAa9B"}

package/dist/trash.js

@@ -0,0 +1,80 @@
+import { Timestamp } from 'firebase-admin/firestore';
+import { getDb } from './firestore.js';
+import { NotFoundError } from './errors.js';
+
+const TRASH_COLLECTION = "_trash";
+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,
+      data: originalData
+    };
+    transaction.set(trashRef, trashData);
+    transaction.delete(originalRef);
+    return {
+      id: trashRef.id,
+      ...trashData
+    };
+  });
+}
+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);
+  });
+}
+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();
+}
+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()
+  }));
+}
+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()
+  };
+}
+
+export { getTrashItem, listTrash, moveToTrash, permanentDelete, restoreFromTrash };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",