@progressive-development/pd-provider-firebase-functions 1.0.1 → 1.2.0

package/dist/auth-trash.d.ts

@@ -1,4 +1,4 @@
-import { TrashItem } from './trash';
+import { TrashItem } from './trash.js';
 export interface AuthTrashOptions {
     /**
      * How to determine the Auth UID from the document.
@@ -23,7 +23,10 @@ export interface AuthTrashOptions {
  * @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>>;
+export declare function moveToTrashWithAuth<T = unknown>(collection: string, documentId: string, deletedBy: string | {
+    uid: string;
+    name: string;
+}, objectType: string, options?: AuthTrashOptions): Promise<TrashItem<T>>;
 /**
  * Restore document from trash AND re-enable the Auth user.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"auth-trash.d.ts","sourceRoot":"","sources":["../src/auth-trash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,SAAS,CAAC;AAQjB,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEtC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoCD;;;;;;;;;;;;;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,CA0CvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"auth-trash.d.ts","sourceRoot":"","sources":["../src/auth-trash.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,aAAa,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAEtC,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAoCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EACnD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CA0CvB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAuCf;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,IAAI,CAAC,CAmCf"}

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
 import { CallableRequest } from 'firebase-functions/v2/https';
-import { AuthContext } from './types';
+import { AuthContext } from './types.js';
 /**
  * Require authenticated user
  */

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CASjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,WAAW,CAUb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,eAAe,EAAE,MAAM,GACtB,IAAI,CAMN"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CASjE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,WAAW,CAUb;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,eAAe,EAAE,MAAM,GACtB,IAAI,CAMN"}

package/dist/changes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A single field change.
+ * Absent sides are stored as null (not undefined — ignoreUndefinedProperties
+ * would drop the key on a Firestore write).
+ */
+export interface FieldChange {
+    old: unknown;
+    new: unknown;
+}
+/** Field name → change. Granularity is the top-level field. */
+export type FieldChanges = Record<string, FieldChange>;
+export interface ComputeChangesOptions {
+    /** Top-level fields to skip when comparing (e.g. "lastEdit"). */
+    ignoreFields?: string[];
+}
+/**
+ * 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
+ */
+export declare function computeChanges(before: Record<string, unknown> | undefined, after: Record<string, unknown>, options?: ComputeChangesOptions): FieldChanges | undefined;
+//# sourceMappingURL=changes.d.ts.map

package/dist/changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.d.ts","sourceRoot":"","sources":["../src/changes.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;CACd;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAkFD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,YAAY,GAAG,SAAS,CAiB1B"}

package/dist/changes.js

@@ -0,0 +1,69 @@
+function hasIsEqual(value) {
+  return typeof value === "object" && value !== null && typeof value.isEqual === "function";
+}
+function isUnset(value) {
+  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;
+}
+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;
+}
+
+export { computeChanges };

package/dist/changes.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=changes.spec.d.ts.map

package/dist/changes.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes.spec.d.ts","sourceRoot":"","sources":["../src/changes.spec.ts"],"names":[],"mappings":""}

package/dist/history.d.ts

@@ -0,0 +1,83 @@
+import { Timestamp } from 'firebase-admin/firestore';
+import { FieldChanges } from './changes.js';
+/**
+ * Core event categories — fixed in the helper. App-specific semantics go
+ * into the free-form `action` field, NOT in here.
+ */
+export declare const HistoryKind: {
+    readonly CREATED: "created";
+    readonly UPDATED: "updated";
+    readonly DELETED: "deleted";
+    readonly RESTORED: "restored";
+    readonly PROCESS: "process";
+};
+export type HistoryKind = (typeof HistoryKind)[keyof typeof HistoryKind];
+/**
+ * A history event for an object.
+ * History is an append-only event log per object, not a snapshot/version
+ * system. Entries survive deletion of the object.
+ */
+export interface HistoryEntry {
+    /** Auto-generated history document ID */
+    id: string;
+    /** Collection of the object (e.g., "locations") */
+    objectCollection: string;
+    /** Document ID of the object */
+    objectId: string;
+    /** Object type for filtering, same convention as trash (e.g., "location") */
+    objectType: string;
+    /** Core event category */
+    kind: HistoryKind;
+    /** When the event was recorded (server-side) */
+    at: Timestamp;
+    /** App-specific action (vocabulary owned by the app, e.g., "verify") */
+    action?: string;
+    /** UID of the authenticated actor */
+    userId?: string;
+    /** Label for non-authenticated/system actors (e.g., "cron", "import-script") */
+    actorLabel?: string;
+    /** Channel/entry point (app vocabulary: "member-app", "admin", "cron", …) */
+    app?: string;
+    /** Free text for display */
+    message?: string;
+    /** Field diff, usually only for kind=updated */
+    changes?: FieldChanges;
+}
+/** Input for a new entry — everything except id and at. */
+export type NewHistoryEntry = Omit<HistoryEntry, "id" | "at">;
+/**
+ * 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
+ */
+export declare function addHistoryEntry(entry: NewHistoryEntry, databaseId?: string): Promise<HistoryEntry>;
+/**
+ * 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
+ */
+export declare function recordHistory(entry: NewHistoryEntry, databaseId?: string): Promise<HistoryEntry | 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
+ */
+export declare function listHistory(objectCollection: string, objectId: string, limit?: number, databaseId?: string): Promise<HistoryEntry[]>;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAIrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAYjD;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;CAMd,CAAC;AACX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,gDAAgD;IAChD,EAAE,EAAE,SAAS,CAAC;IACd,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC,CAAC;AAS9D;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAmBvB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,eAAe,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAY9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAY,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,EAAE,CAAC,CAczB"}

package/dist/history.js

@@ -0,0 +1,53 @@
+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"
+};
+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
+  };
+}
+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;
+  }
+}
+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()
+  }));
+}
+
+export { HistoryKind, addHistoryEntry, listHistory, recordHistory };

package/dist/index.d.ts

@@ -1,17 +1,23 @@
-export type { ApiResponse, AuthContext } from './types';
-export { StatusCode } from './types';
-export { AppError, ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, EmailAlreadyUsedError, SC_EMAIL_ALREADY_USED, } from './errors';
-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';
-export type { LogType, ScriptContextConfig, ScriptContext, } from './script-helpers';
-export { scriptLog, initFirebaseAdmin, createScriptContext, } from './script-helpers';
-export type { ImportTemplatesConfig } from './import-templates';
-export { runImportTemplates } from './import-templates';
+export type { ApiResponse, AuthContext } from './types.js';
+export { StatusCode } from './types.js';
+export { AppError, ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, EmailAlreadyUsedError, SC_EMAIL_ALREADY_USED, } from './errors.js';
+export { requireAuth, requireClaims, requireOwnership } from './auth.js';
+export { success, created, handleError } from './response.js';
+export { getDb } from './firestore.js';
+export { getNextCounter } from './counter.js';
+export type { TrashItem } from './trash.js';
+export { moveToTrash, restoreFromTrash, permanentDelete, listTrash, getTrashItem, } from './trash.js';
+export type { AuthTrashOptions } from './auth-trash.js';
+export { moveToTrashWithAuth, restoreFromTrashWithAuth, permanentDeleteWithAuth, } from './auth-trash.js';
+export type { FieldChange, FieldChanges, ComputeChangesOptions, } from './changes.js';
+export { computeChanges } from './changes.js';
+export type { HistoryEntry, NewHistoryEntry } from './history.js';
+export { HistoryKind, addHistoryEntry, recordHistory, listHistory, } from './history.js';
+export type { MailObject, MailTemplate, MailMessage, MailAttachment, StoredMail, } from './mail.js';
+export { addMailForSend, getMailById, getMailsByField } from './mail.js';
+export { logger } from './logger.js';
+export type { LogType, ScriptContextConfig, ScriptContext, } from './script-helpers.js';
+export { scriptLog, initFirebaseAdmin, createScriptContext, } from './script-helpers.js';
+export type { ImportTemplatesConfig } from './import-templates.js';
+export { runImportTemplates } from './import-templates.js';
 //# 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,EACL,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,UAAU,CAAC;AAGlB,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,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,GACd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAG1B,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACL,QAAQ,EACR,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG9D,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AAGzB,YAAY,EACV,WAAW,EACX,YAAY,EACZ,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,UAAU,GACX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGzE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,YAAY,EACV,OAAO,EACP,mBAAmB,EACnB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAG7B,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -6,6 +6,9 @@ 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 { 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';

package/dist/mail.d.ts

@@ -0,0 +1,79 @@
+import { Timestamp } from 'firebase-admin/firestore';
+export interface MailAttachment {
+    filename: string;
+    path: string;
+    contentType?: string;
+}
+/** Template-based mail: the extension renders template `name` with `data`. */
+export interface MailTemplate {
+    name: string;
+    data: Record<string, unknown>;
+    attachments?: MailAttachment[];
+}
+/** Direct mail content, used when no template is involved. */
+export interface MailMessage {
+    subject: string;
+    html: string;
+    text?: string;
+    attachments?: MailAttachment[];
+}
+/**
+ * Core mail shape — the fields consumed by the Firebase mail extension.
+ * Apps extend this with their own correlation fields (e.g. eventId, counter)
+ * via the generic parameter of the mail functions.
+ */
+export interface MailObject {
+    to: string;
+    cc?: string;
+    bcc?: string;
+    replyTo?: string;
+    template?: MailTemplate;
+    message?: MailMessage;
+}
+/** A stored mail document, including extension-written delivery state. */
+export type StoredMail<T extends MailObject = MailObject> = T & {
+    /** Auto-generated mail document ID */
+    id: string;
+    /** When the mail document was created (server-side) */
+    creation: Timestamp;
+    /** Delivery state, written by the mail extension */
+    delivery?: unknown;
+};
+/**
+ * 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
+ */
+export declare function addMailForSend<T extends MailObject>(mail: T, collection?: string, databaseId?: string): Promise<string>;
+/**
+ * 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
+ */
+export declare function getMailById<T extends MailObject>(mailId: string, collection?: string, databaseId?: string): Promise<StoredMail<T> | null>;
+/**
+ * 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
+ */
+export declare function getMailsByField<T extends MailObject>(field: string, value: unknown, collection?: string, limit?: number, databaseId?: string): Promise<StoredMail<T>[]>;
+//# sourceMappingURL=mail.d.ts.map

package/dist/mail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.d.ts","sourceRoot":"","sources":["../src/mail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAcrD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,UAAU,GAAG,UAAU,IAAI,CAAC,GAAG;IAC9D,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,QAAQ,EAAE,SAAS,CAAC;IACpB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,UAAU,EACvD,IAAI,EAAE,CAAC,EACP,UAAU,GAAE,MAAgC,EAC5C,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,UAAU,EACpD,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,MAAgC,EAC5C,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAY/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,eAAe,CAAC,CAAC,SAAS,UAAU,EACxD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,OAAO,EACd,UAAU,GAAE,MAAgC,EAC5C,KAAK,GAAE,MAAY,EACnB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAe1B"}

package/dist/mail.js

@@ -0,0 +1,42 @@
+import { Timestamp } from 'firebase-admin/firestore';
+import { getDb } from './firestore.js';
+import { ValidationError } from './errors.js';
+
+const DEFAULT_MAIL_COLLECTION = "mail";
+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;
+}
+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()
+  };
+}
+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()
+    })
+  );
+}
+
+export { addMailForSend, getMailById, getMailsByField };

package/dist/response.d.ts

@@ -1,4 +1,4 @@
-import { ApiResponse } from './types';
+import { ApiResponse } from './types.js';
 export declare function success<T>(data: T): ApiResponse<T>;
 export declare function created<T>(data: T): ApiResponse<T>;
 export declare function handleError(error: unknown): ApiResponse<{

package/dist/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAIlD,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,GACb,WAAW,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9C"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../src/response.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AAIrD,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,GACb,WAAW,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB9C"}

package/dist/trash.d.ts

@@ -16,6 +16,9 @@ export interface TrashItem<T = unknown> {
     deletedAt: Timestamp;
     /** UID of user who deleted */
     deletedBy: string;
+    /** Denormalized display name of the deleting user (survives account
+     *  deletion; written when moveToTrash receives a stamp object) */
+    deletedByName?: string;
     /** The original document data */
     data: T;
 }
@@ -29,13 +32,17 @@ export interface TrashItem<T = unknown> {
  *
  * @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 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
  */
-export declare function moveToTrash<T = unknown>(collection: string, documentId: string, deletedBy: string, objectType: string, databaseId?: string): Promise<TrashItem<T>>;
+export declare function moveToTrash<T = unknown>(collection: string, documentId: string, deletedBy: string | {
+    uid: string;
+    name: string;
+}, objectType: string, databaseId?: string): Promise<TrashItem<T>>;
 /**
  * Restore a document from trash to its original location.
  *

package/dist/trash.d.ts.map

@@ -1 +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"}
+{"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;sEACkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,IAAI,EAAE,CAAC,CAAC;CACT;AASD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EACjD,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAsCvB;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

@@ -18,7 +18,10 @@ async function moveToTrash(collection, documentId, deletedBy, objectType, databa
       originalCollection: collection,
       objectType,
       deletedAt: Timestamp.now(),
-      deletedBy,
+      deletedBy: typeof deletedBy === "string" ? deletedBy : deletedBy.uid,
+      ...typeof deletedBy === "object" && {
+        deletedByName: deletedBy.name
+      },
       data: originalData
     };
     transaction.set(trashRef, trashData);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progressive-development/pd-provider-firebase-functions",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Firebase Functions v2 utilities for pd-spa-helper backend",
   "author": "PD Progressive Development",
   "license": "SEE LICENSE IN LICENSE",
@@ -39,6 +39,7 @@
     "clean:all": "rm -rf dist node_modules pnpm-lock.yaml",
     "lint": "eslint --ext .ts src --ignore-path ../../.eslintignore && prettier \"**/*.ts\" --check --ignore-path ../../.eslintignore",
     "format": "eslint --ext .ts src --fix --ignore-path ../../.eslintignore && prettier \"**/*.ts\" --write --ignore-path ../../.eslintignore",
-    "check": "pnpm run lint && pnpm run build"
+    "check": "pnpm run lint && pnpm run build",
+    "test": "vitest run"
   }
 }