@plusscommunities/pluss-core-aws 2.0.25-auth.0 → 2.0.25-beta.1

package/helper/getUserPreview.js

@@ -3,66 +3,66 @@ const getUser = require("../db/users/getUser");
 const { getConfig } = require("../config");
 
 module.exports = async (id, includeType, includeSite, options) => {
-  return new Promise((resolve, reject) => {
-    const logId = log("getUserPreview", "Input", {
-      id,
-      includeType,
-      includeSite,
-      options,
-    });
+	return new Promise((resolve, reject) => {
+		const logId = log("getUserPreview", "Input", {
+			id,
+			includeType,
+			includeSite,
+			options,
+		});
 
-    if (!id) {
-      log("getUserPreview", "NoId", "id is missing", logId);
-      return resolve({
-        id: null,
-        userId: null,
-        displayName: "Pluss",
-        profilePic: null,
-        type: null,
-        site: getConfig().anySignUpSite,
-      });
-    }
+		if (!id) {
+			log("getUserPreview", "NoId", "id is missing", logId);
+			return resolve({
+				id: null,
+				userId: null,
+				displayName: "Pluss",
+				profilePic: null,
+				type: null,
+				site: getConfig().anySignUpSite,
+			});
+		}
 
-    getUser(id)
-      .then((user) => {
-        const returnObj = {
-          id,
-          userId: id,
-          displayName: user.displayName,
-          profilePic: user.profilePic || null,
-        };
+		getUser(id)
+			.then((user) => {
+				const returnObj = {
+					id,
+					userId: id,
+					displayName: user.displayName,
+					profilePic: user.profilePic || null,
+				};
 
-        if (includeType || includeSite) {
-          returnObj.Roles = user.Roles;
-          if (!user.Roles) {
-            returnObj.Roles = [
-              {
-                type: user.type,
-                site: user.site,
-              },
-            ];
-          }
-        }
+				if (includeType || includeSite) {
+					returnObj.Roles = user.Roles;
+					if (!user.Roles) {
+						returnObj.Roles = [
+							{
+								type: user.type,
+								site: user.site,
+							},
+						];
+					}
+				}
 
-        if (includeType) {
-          returnObj.type = user.type || null;
-        }
-        if (includeSite) {
-          returnObj.site = user.site || null;
-        }
-        if (options) {
-          if (options.includeEmail) {
-            returnObj.email = user.email !== "empty" ? user.email : null;
-          }
-        }
-        log("getUserPreview", "Result", returnObj, logId);
+				if (includeType) {
+					returnObj.type = user.type || null;
+				}
+				if (includeSite) {
+					returnObj.site = user.site || null;
+				}
+				if (options) {
+					if (options.includeEmail) {
+						returnObj.email = user.email !== "empty" ? user.email : null;
+					}
+				}
+				log("getUserPreview", "Result", returnObj, logId);
 
-        resolve(returnObj);
-      })
-      .catch((error) => {
-        log("getUserPreview", "Error", error, logId);
-        console.log("failed to get user preview", id);
-        reject(error);
-      });
-  });
+				resolve(returnObj);
+			})
+			.catch((error) => {
+				log("getUserPreview", "Error", error, logId);
+				console.log("failed to get user preview", id);
+				reject(error);
+			});
+	});
 };

package/helper/getUserPreviewFromHeader.js

@@ -3,21 +3,21 @@ const getSessionUser = require("./auth/getSessionUser");
 const getUserPreview = require("./getUserPreview");
 
 module.exports = async (authkey, includeType, inlcudeSite, options) => {
-  return new Promise((resolve, reject) => {
-    getSessionUser(authkey)
-      .then((uid) => {
-        getUserPreview(uid, includeType, inlcudeSite, options)
-          .then((user) => {
-            resolve(user);
-          })
-          .catch((error) => {
-            log("getUserPreviewFromHeader", "Error:getUserPreview", error);
-            reject(error);
-          });
-      })
-      .catch((error) => {
-        log("getUserPreviewFromHeader", "Error:getSessionUser", error);
-        reject(error);
-      });
-  });
+	return new Promise((resolve, reject) => {
+		getSessionUser(authkey)
+			.then((uid) => {
+				getUserPreview(uid, includeType, inlcudeSite, options)
+					.then((user) => {
+						resolve(user);
+					})
+					.catch((error) => {
+						log("getUserPreviewFromHeader", "Error:getUserPreview", error);
+						reject(error);
+					});
+			})
+			.catch((error) => {
+				log("getUserPreviewFromHeader", "Error:getSessionUser", error);
+				reject(error);
+			});
+	});
 };

package/helper/getUserPreviewFromReq.js

@@ -2,21 +2,21 @@ const getSessionUserFromReqAuthKey = require("./auth/getSessionUserFromReqAuthKe
 const getUserPreview = require("./getUserPreview");
 
 module.exports = async (req, includeType, inlcudeSite, options) => {
-  return new Promise((resolve, reject) => {
-    getSessionUserFromReqAuthKey(req)
-      .then((uid) => {
-        getUserPreview(uid, includeType, inlcudeSite, options)
-          .then((user) => {
-            resolve(user);
-          })
-          .catch((error) => {
-            console.log("failed to get user preview", uid);
-            reject(error);
-          });
-      })
-      .catch((error) => {
-        console.log("failed to get session user", authkey);
-        reject(error);
-      });
-  });
+	return new Promise((resolve, reject) => {
+		getSessionUserFromReqAuthKey(req)
+			.then((uid) => {
+				getUserPreview(uid, includeType, inlcudeSite, options)
+					.then((user) => {
+						resolve(user);
+					})
+					.catch((error) => {
+						console.log("failed to get user preview", uid);
+						reject(error);
+					});
+			})
+			.catch((error) => {
+				console.log("failed to get session user", req);
+				reject(error);
+			});
+	});
 };

package/helper/hqPublishing.js

@@ -0,0 +1,337 @@
+/**
+ * PC-1441 Epic 1 — Cross-site Publishing Framework primitives (§13).
+ *
+ * Entity-agnostic helpers for HQ-published content lifecycle. Newsletter is the
+ * first entity to adopt this in July 2026 (Stories A–F under PC-1441); Q4+
+ * entities (Surveys, Information, Facilities, Services) plug in by depending on
+ * the same primitives — `HqSourceId` / `PublishedToSites` / `TemplateId` are
+ * universal field conventions, the helpers below don't reference any newsletter-
+ * specific table or shape.
+ *
+ * Story coverage:
+ * - **Story A (PC-1443)** — `isHqLocked` (lock guard for community-copy mutations).
+ * - **Story B (PC-1444)** — adds `findCopiesByHqSourceId`, `fanOutHqSource`,
+ *   `propagateHqEdit`, `cascadeHqRetract`, and `incrementTemplateUseCount`.
+ *
+ * If this file grows beyond ~300 lines or develops sub-themes, refactor to a
+ * `hqPublishing/` subdirectory with `index.js` re-exports.
+ */
+
+const AWS = require("aws-sdk");
+const moment = require("moment");
+const indexQuery = require("../db/common/indexQuery");
+const updateRef = require("../db/common/updateRef");
+const editRef = require("../db/common/editRef");
+
+// Raw DocumentClient for atomic-increment operations that editRef can't do
+// safely under concurrent stream-handler invocations.
+const dynamoDb = new AWS.DynamoDB.DocumentClient({ convertEmptyValues: true });
+
+/**
+ * Fields owned by each community copy independently — never overwritten on
+ * propagation from the HQ-source row. Other entities can pass a wider list via
+ * `propagateHqEdit`'s `protectedFields` param if their schema has more identity
+ * columns.
+ */
+const DEFAULT_PROTECTED_FIELDS = [
+	"Id",
+	"RowId",
+	"Site",
+	"HqSourceId",
+	"PublishedToSites",     // HQ-only field; copies don't carry the multi-site list
+	"UnsentNotification",   // each copy's notification state is independent
+	"Deleted",              // cascadeHqRetract is the dedicated path; propagateHqEdit must not touch this
+];
+
+// ---------------------------------------------------------------------------
+// Story A — lock guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns `true` when the entry is a community copy of an HQ-published post —
+ * i.e. its `HqSourceId` is **truthy**.
+ *
+ * **Falsy test (`Boolean(HqSourceId)`) — NOT `!== null`.** Legacy entries and
+ * locally-created entries have `HqSourceId` `undefined`; `undefined !== null`
+ * evaluates to `true`, which would wrongly lock every pre-feature post. The
+ * falsy check accepts `undefined`, `null`, and `""` as "not locked." See PC-1441
+ * scoping doc §3.2 AC2.3 + §6.1 + commit `1123c79` on `docs/enterprise-roadmap-scoping`.
+ *
+ * Universal — no role-based exception, including masters. HQ users edit the
+ * HQ-source row (where `!HqSourceId`, so the lock does not apply); the stream
+ * cascades to community copies. This is the API-side gate that pairs with the
+ * admin UI lock indicator (PC-1448) — defense-in-depth.
+ *
+ * @param {object|null|undefined} entry - Any object with an `HqSourceId` field
+ *   (typically a row fetched from the entity's DB table).
+ * @returns {boolean} `true` if the entry is a locked community copy; `false`
+ *   for legacy / locally-authored / HQ-source rows.
+ */
+const isHqLocked = (entry) => Boolean(entry?.HqSourceId);
+
+// ---------------------------------------------------------------------------
+// Story B — fan-out, propagation, retract cascade, UseCount
+// ---------------------------------------------------------------------------
+
+/**
+ * Query the GSI on `HqSourceId` to locate every community copy of a given HQ
+ * source row. Returns the full row data (the GSI uses `Projection: ALL` so
+ * follow-up reads aren't needed).
+ *
+ * @param {string} hqSourceId — the `Id` of the HQ-source row.
+ * @param {string} tableName — entity's table name (without prefix; helper
+ *   prepends `process.env.tablePrefix`).
+ * @param {string} [indexName="NewsletterEntriesHqSourceIdIndex"] — GSI name.
+ *   Other entities pass their own index name.
+ * @returns {Promise<object[]>} array of copy rows; `[]` if no copies exist
+ *   (HQ source has no fan-out yet).
+ */
+const findCopiesByHqSourceId = async (
+	hqSourceId,
+	tableName,
+	indexName = "NewsletterEntriesHqSourceIdIndex",
+) => {
+	if (!hqSourceId) {
+		return [];
+	}
+	const result = await indexQuery(tableName, {
+		IndexName: indexName,
+		KeyConditionExpression: "HqSourceId = :sid",
+		ExpressionAttributeValues: { ":sid": hqSourceId },
+	});
+	return result?.Items || [];
+};
+
+/**
+ * Fan out one community-copy row per target site listed in
+ * `hqSourceRow.PublishedToSites`. Each copy carries:
+ *   - **Deterministic RowId** `${targetSiteId}_hqcopy-${hqSourceRow.Id}` so
+ *     re-fires of the stream INSERT event become idempotent put-with-same-key
+ *     operations (no duplicates).
+ *   - `Id` derived from `hqcopy-${hqSourceRow.Id}` (mirrors the deterministic
+ *     RowId; stable across stream re-fires).
+ *   - `Site: targetSiteId` and `HqSourceId: hqSourceRow.Id` (the lock-guard
+ *     anchor).
+ *   - Full denormalised content from the HQ-source row, MINUS HQ-only fields
+ *     (`PublishedToSites`) and identity fields the copy owns independently.
+ *   - Fresh `UnixTimestamp` per copy so each community's feed sees the post as
+ *     "now-published" rather than the HQ-source's creation time.
+ *
+ * Caller (the entity's stream handler) is responsible for SKIPPING
+ * `publishNotifications` on the HQ-source INSERT — notifications fire natively
+ * on each copy's own INSERT stream event downstream (per AC1.4 / U1.2).
+ *
+ * @param {object} hqSourceRow — the HQ-source row from the stream NewImage.
+ * @param {string} tableName — entity's table name.
+ * @returns {Promise<object[]>} array of the copy rows written.
+ */
+const fanOutHqSource = async (hqSourceRow, tableName) => {
+	if (!hqSourceRow || hqSourceRow.Site !== "hq") {
+		return [];
+	}
+	const targets = Array.isArray(hqSourceRow.PublishedToSites)
+		? hqSourceRow.PublishedToSites
+		: [];
+	if (targets.length === 0) {
+		return [];
+	}
+	const copyId = `hqcopy-${hqSourceRow.Id}`;
+	const now = moment.utc().unix();
+
+	const writes = targets.map((targetSiteId) => {
+		// Spread + override pattern: keep all content fields, swap identity
+		// fields, drop HQ-only fields. Spread is shallow — nested objects
+		// (Author, etc.) share references with the source row, which is fine
+		// because we're writing to a separate row and DDB serialises by value.
+		const copy = { ...hqSourceRow };
+		copy.Id = copyId;
+		copy.Site = targetSiteId;
+		copy.RowId = `${targetSiteId}_${copyId}`;
+		copy.HqSourceId = hqSourceRow.Id;
+		copy.UnixTimestamp = now;
+		copy.UnixTimestampReverse = Number.MAX_SAFE_INTEGER - now;
+		// Each copy's own INSERT fires publishNotifications via the existing
+		// pipeline. Setting UnsentNotification: "X" matches the convention
+		// used by addNewsletterEntry when caller requested a notification.
+		copy.UnsentNotification = hqSourceRow.UnsentNotification || "X";
+		// HQ-only fields don't travel:
+		delete copy.PublishedToSites;
+		delete copy.Deleted;     // copies start undeleted; retract cascade is separate
+		return updateRef(tableName, copy).then(() => copy);
+	});
+	return Promise.all(writes);
+};
+
+/**
+ * Propagate an HQ-source MODIFY to every community copy via the GSI lookup.
+ * Skips the retract case (where `Deleted: true`) — that flows through
+ * `cascadeHqRetract` instead.
+ *
+ * Identity fields the copy owns independently (Id, RowId, Site, HqSourceId,
+ * PublishedToSites, UnsentNotification, Deleted) are NEVER overwritten. Other
+ * entities can extend the protected list via `options.protectedFields`.
+ *
+ * Latency target per §3.1 AC1.5: end-to-end within 30s. Each copy gets a
+ * separate `editRef` call (get-merge-put); they run in parallel.
+ *
+ * @param {object} hqSourceRow — NewImage of the HQ-source row from the stream.
+ * @param {object} _prevRow — OldImage (currently unused; reserved for future
+ *   delta-diff optimisation when we want to skip propagation on no-op changes).
+ * @param {string} tableName — entity's table name.
+ * @param {object} [options]
+ * @param {string} [options.indexName="NewsletterEntriesHqSourceIdIndex"]
+ * @param {string[]} [options.protectedFields=DEFAULT_PROTECTED_FIELDS]
+ * @returns {Promise<number>} count of copies updated.
+ */
+const propagateHqEdit = async (
+	hqSourceRow,
+	_prevRow,
+	tableName,
+	options = {},
+) => {
+	const protectedFields =
+		options.protectedFields || DEFAULT_PROTECTED_FIELDS;
+	const indexName =
+		options.indexName || "NewsletterEntriesHqSourceIdIndex";
+
+	if (!hqSourceRow || hqSourceRow.Site !== "hq" || hqSourceRow.Deleted) {
+		return 0;
+	}
+
+	const copies = await findCopiesByHqSourceId(
+		hqSourceRow.Id,
+		tableName,
+		indexName,
+	);
+	if (copies.length === 0) {
+		return 0;
+	}
+
+	// Build the propagation payload: everything from the HQ-source row EXCEPT
+	// protected identity fields.
+	const propagated = { ...hqSourceRow };
+	for (const field of protectedFields) {
+		delete propagated[field];
+	}
+	propagated.Changed = moment.utc().unix();
+
+	await Promise.all(
+		copies.map((copy) =>
+			editRef(tableName, "RowId", copy.RowId, propagated),
+		),
+	);
+	return copies.length;
+};
+
+/**
+ * Cascade `Deleted: true` to every community copy when the HQ-source row is
+ * retracted (`Deleted: true` set on the HQ-source MODIFY). Per §12.2, data is
+ * preserved at the storage layer — only the `Deleted` flag flips; no rows are
+ * removed. Un-retract UI is out of scope this iteration.
+ *
+ * @param {object} hqSourceRow — NewImage of the retracted HQ-source row.
+ * @param {string} tableName — entity's table name.
+ * @param {object} [options]
+ * @param {string} [options.indexName="NewsletterEntriesHqSourceIdIndex"]
+ * @returns {Promise<number>} count of copies marked deleted.
+ */
+const cascadeHqRetract = async (hqSourceRow, tableName, options = {}) => {
+	const indexName =
+		options.indexName || "NewsletterEntriesHqSourceIdIndex";
+
+	if (!hqSourceRow || hqSourceRow.Site !== "hq" || !hqSourceRow.Deleted) {
+		return 0;
+	}
+
+	const copies = await findCopiesByHqSourceId(
+		hqSourceRow.Id,
+		tableName,
+		indexName,
+	);
+	if (copies.length === 0) {
+		return 0;
+	}
+
+	const deletionUpdate = {
+		Deleted: true,
+		Changed: moment.utc().unix(),
+	};
+	await Promise.all(
+		copies.map((copy) =>
+			editRef(tableName, "RowId", copy.RowId, deletionUpdate),
+		),
+	);
+	return copies.length;
+};
+
+/**
+ * Atomically increment `UseCount` on a `contentLibrary` template row when a
+ * new entity row is created from that template (`TemplateId !== null`).
+ *
+ * **Atomic** — uses DDB `UpdateExpression: ADD UseCount :inc` rather than
+ * get-merge-put so concurrent stream invocations don't clobber each other's
+ * increments. (`editRef`'s get-then-put pattern would race here.)
+ *
+ * **Graceful degradation while Story C unshipped**: when the `contentLibrary`
+ * table doesn't exist yet (C / PC-1445 has not shipped), DDB raises
+ * `ResourceNotFoundException`. Helper catches it, logs INFO, and returns
+ * `false` — does NOT throw. This lets Story B ship independent of Story C
+ * (per PC-1444 AC-B.3 graceful-degradation clause).
+ *
+ * **Cross-account UseCount aggregation is out of scope** — Pluss Library uses
+ * across all clients are NOT counted here (§12.4 deferred).
+ *
+ * @param {string} templateId — the `Id` of the contentLibrary row.
+ * @param {string} contentLibraryTable — entity-agnostic; caller passes the
+ *   table name (without prefix).
+ * @returns {Promise<boolean>} `true` if increment applied; `false` if table
+ *   doesn't exist (graceful skip).
+ */
+const incrementTemplateUseCount = async (templateId, contentLibraryTable) => {
+	if (!templateId || !contentLibraryTable) {
+		return false;
+	}
+	const params = {
+		TableName: `${process.env.tablePrefix}${contentLibraryTable}`,
+		Key: { Id: templateId },
+		UpdateExpression:
+			"ADD UseCount :inc SET LastUsedTimestamp = :now",
+		ExpressionAttributeValues: {
+			":inc": 1,
+			":now": moment.utc().unix(),
+		},
+	};
+	try {
+		await dynamoDb.update(params).promise();
+		return true;
+	} catch (error) {
+		if (error?.code === "ResourceNotFoundException") {
+			// Graceful degradation while Story C (contentLibrary table) is
+			// unshipped — see AC-B.3. Not an error; the rest of the stream
+			// handler should continue.
+			console.log(
+				"incrementTemplateUseCount: contentLibrary table not found — skipped (Story C not yet shipped)",
+			);
+			return false;
+		}
+		// Anything else is genuinely unexpected — surface it.
+		console.error(
+			"incrementTemplateUseCount: unexpected error",
+			error,
+		);
+		throw error;
+	}
+};
+
+module.exports = {
+	// Story A
+	isHqLocked,
+	// Story B
+	findCopiesByHqSourceId,
+	fanOutHqSource,
+	propagateHqEdit,
+	cascadeHqRetract,
+	incrementTemplateUseCount,
+	// Exposed for tests and other entities that want to extend the protected list
+	DEFAULT_PROTECTED_FIELDS,
+};

package/helper/index.js

@@ -3,28 +3,28 @@ const uuid = require("uuid");
 const { encode, decode } = require("html-entities");
 
 exports.thisOrDefault = (val, def) => {
-  if (val) {
-    return val;
-  }
-  return def;
+	if (val) {
+		return val;
+	}
+	return def;
 };
 
 exports.getRowId = (site, id) => {
-  if (_.isEmpty(site)) {
-    return id;
-  }
-  return `${site}_${id}`;
+	if (_.isEmpty(site)) {
+		return id;
+	}
+	return `${site}_${id}`;
 };
 
 exports.getMultiRowId = (cols) => {
-  let result = "";
-  cols.forEach((col) => {
-    if (!_.isEmpty(result)) {
-      result += "_";
-    }
-    result += col;
-  });
-  return result;
+	let result = "";
+	cols.forEach((col) => {
+		if (!_.isEmpty(result)) {
+			result += "_";
+		}
+		result += col;
+	});
+	return result;
 };
 
 // exports.getExtension = (filename) => {
@@ -36,7 +36,7 @@ exports.getMultiRowId = (cols) => {
 // };
 
 exports.getBody = (event) => {
-  return typeof event.body === "string" ? JSON.parse(event.body) : event.body;
+	return typeof event.body === "string" ? JSON.parse(event.body) : event.body;
 };
 
 // exports.generatePassword = () => {
@@ -47,20 +47,20 @@ exports.getBody = (event) => {
 // };
 
 exports.log = (action, logKey, data, logId) => {
-  if (!logId) {
-    logId = this.generateLogId();
-  }
-  console.log(
-    `[${action}]:[${logId}]:[${logKey}]`,
-    typeof data === "string" || typeof data === "number"
-      ? data
-      : JSON.stringify(data)
-  );
-  return logId;
+	if (!logId) {
+		logId = this.generateLogId();
+	}
+	console.log(
+		`[${action}]:[${logId}]:[${logKey}]`,
+		typeof data === "string" || typeof data === "number"
+			? data
+			: JSON.stringify(data),
+	);
+	return logId;
 };
 
 exports.generateLogId = () => {
-  return uuid.v4().substring(30);
+	return uuid.v4().substring(30);
 };
 
 exports.encodeHtml = (html) => encode(html);