@plusscommunities/pluss-core-aws 2.0.26-auth.0 → 2.0.26

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,465 @@
+/**
+ * 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 indexQueryRecursive = require("../db/common/indexQueryRecursive");
+const updateRef = require("../db/common/updateRef");
+const editRef = require("../db/common/editRef");
+const { log } = require("./index");
+
+// 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
+	"UnixTimestamp",        // per-copy fan-out timestamp; HQ-source MODIFY must not rewind copies' feed position
+	"UnixTimestampReverse", //   ↳ paired with UnixTimestamp; same rationale (used as feed-sort key on community sites)
+];
+
+// ---------------------------------------------------------------------------
+// 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 [];
+	}
+	// indexQueryRecursive paginates LastEvaluatedKey internally and returns a
+	// flat array — required because a single GSI query response caps at 1 MiB
+	// and large-content HQ fan-outs to ~50 client sites can exceed that. With
+	// the non-recursive indexQuery, propagateHqEdit + cascadeHqRetract would
+	// silently miss copies on page 2+, leaving them stale after edits and
+	// visible after retractions.
+	const items = await indexQueryRecursive(tableName, {
+		IndexName: indexName,
+		KeyConditionExpression: "HqSourceId = :sid",
+		ExpressionAttributeValues: { ":sid": hqSourceId },
+	});
+	return 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 [];
+	}
+	return writeCopiesForTargets(hqSourceRow, targets, tableName);
+};
+
+/**
+ * Write one community-copy row per site in `targetSites` (all of the source's
+ * PublishedToSites on INSERT fan-out, or just the newly-added subset on a
+ * MODIFY target-set change). Shared by fanOutHqSource and syncHqTargets. The
+ * deterministic RowId makes each write idempotent AND makes re-adding a
+ * previously-removed (soft-deleted) site a lossless resurrection — the PUT
+ * overwrites the row and drops the Deleted flag.
+ *
+ * @param {object} hqSourceRow — the HQ-source row.
+ * @param {string[]} targetSites — sites to write copies for.
+ * @param {string} tableName — entity's table name.
+ * @returns {Promise<object[]>} the copy rows written.
+ */
+const writeCopiesForTargets = (hqSourceRow, targetSites, tableName) => {
+	const copyId = `hqcopy-${hqSourceRow.Id}`;
+	// Preserve the HQ-source row's own UnixTimestamp on each copy rather than
+	// stamping "now". For an immediate publish the source timestamp already IS
+	// ~now, so feed ranking is unchanged; for a SCHEDULED publish (future
+	// timestamp set via the compose "Schedule Post" tab) preserving it keeps the
+	// copies hidden until the scheduled moment — BOTH consumers key off it: the
+	// noFuture feed filter, and the deferred-notification scheduler
+	// (watchNewsletter / the INSERT-path checkSendNotifications both gate on
+	// `UnixTimestamp < now`). Stamping "now" here published scheduled HQ posts
+	// (feed + push) immediately, ignoring the schedule. Fall back to now only if
+	// the source somehow lacks a timestamp.
+	//
+	// IMPORTANT: milliseconds (.valueOf), not seconds (.unix) — parity with the
+	// addNewsletterEntry UnixTimestamp convention. UnixTimestampReverse-keyed
+	// feed queries would otherwise mis-rank an ms value against a seconds value
+	// (MAX_SAFE_INTEGER minus 10^9 vs minus 10^12).
+	const now = moment.utc().valueOf();
+	const publishTs = hqSourceRow.UnixTimestamp || now;
+
+	const writes = targetSites.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 = publishTs;
+		copy.UnixTimestampReverse = Number.MAX_SAFE_INTEGER - publishTs;
+		// 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
+		// Tagged references HQ-site users; on a community copy those IDs are
+		// orphaned (cosmetic "tagged people" display + a createUserEntries write
+		// keyed on non-members in newsletterChanged's INSERT branch). Audience
+		// targeting (All/Category) already governs who sees the copy.
+		delete copy.Tagged;
+		return updateRef(tableName, copy).then(() => copy);
+	});
+	return Promise.all(writes);
+};
+
+/**
+ * Reconcile community copies when an HQ-source MODIFY changes PublishedToSites:
+ * fan out copies for newly-ADDED sites, soft-delete copies for REMOVED sites.
+ * Content propagation to surviving copies is propagateHqEdit's job; this only
+ * reconciles the target SET. Re-adding a removed site resurrects its copy
+ * losslessly (deterministic RowId + PUT — see writeCopiesForTargets).
+ *
+ * MUST run sequentially relative to propagateHqEdit (never concurrently): both
+ * use editRef (get-merge-put), and two concurrent writes to the same removed-
+ * copy RowId would race (one clobbering the other's Deleted flag).
+ *
+ * @param {object} prevRow — OldImage of the HQ-source row.
+ * @param {object} nextRow — NewImage of the HQ-source row.
+ * @param {string} tableName — entity's table name.
+ * @param {object} [options]
+ * @param {string} [options.indexName="NewsletterEntriesHqSourceIdIndex"]
+ * @returns {Promise<{added: number, removed: number}>}
+ */
+const syncHqTargets = async (prevRow, nextRow, tableName, options = {}) => {
+	const indexName = options.indexName || "NewsletterEntriesHqSourceIdIndex";
+	if (!nextRow || nextRow.Site !== "hq" || nextRow.Deleted) {
+		return { added: 0, removed: 0 };
+	}
+	const prev = Array.isArray(prevRow?.PublishedToSites)
+		? prevRow.PublishedToSites
+		: [];
+	const next = Array.isArray(nextRow.PublishedToSites)
+		? nextRow.PublishedToSites
+		: [];
+	const added = next.filter((s) => !prev.includes(s));
+	const removed = prev.filter((s) => !next.includes(s));
+
+	if (added.length > 0) {
+		await writeCopiesForTargets(nextRow, added, tableName);
+	}
+	if (removed.length > 0) {
+		const copies = await findCopiesByHqSourceId(
+			nextRow.Id,
+			tableName,
+			indexName,
+		);
+		const toRemove = copies.filter((c) => removed.includes(c.Site));
+		// Per-call fresh payload — editRef sync-mutates updates[keyCol]; sharing
+		// across Promise.all(map) would leak RowId between iterations (same
+		// rationale as propagateHqEdit / cascadeHqRetract).
+		await Promise.all(
+			toRemove.map((c) =>
+				editRef(tableName, "RowId", c.RowId, {
+					Deleted: true,
+					Changed: moment.utc().unix(),
+				}),
+			),
+		);
+	}
+	return { added: added.length, removed: removed.length };
+};
+
+/**
+ * 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();
+
+	// IMPORTANT: pass a fresh shallow copy per call. `editRef` synchronously
+	// mutates its `updates` argument (`updates[keyCol] = id` inside the Promise
+	// constructor) AFTER taking a `cloneDeep` snapshot. Across parallel
+	// `Promise.all(map(...))` invocations, iteration N's `cloneDeep` would
+	// capture iteration N-1's `RowId` mutation, then later overwrite copy N's
+	// `RowId` during the get-merge-put, writing copy N's content back to copy
+	// N-1's key (and leaving copy N's own row untouched). Per-call `{...propagated}`
+	// gives each invocation an isolated payload it can mutate safely.
+	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(),
+	};
+	// Per-call shallow copy — see propagateHqEdit for the editRef-mutation-race
+	// rationale. Even though `deletionUpdate` is tiny, the same RowId clobber
+	// happens here: under sharing, only the FIRST copy actually receives
+	// `Deleted: true`; subsequent writes land at the wrong RowId.
+	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` on graceful
+ *   skip (table not shipped yet, or no template with that Id exists).
+ */
+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",
+		// Guard against minting a phantom row: ADD on a missing key would CREATE
+		// it with UseCount=1. Only increment a template that actually exists; a
+		// stale/bogus TemplateId is skipped (ConditionalCheckFailed below).
+		ConditionExpression: "attribute_exists(Id)",
+		ExpressionAttributeValues: {
+			":inc": 1,
+			// epoch ms — the contentLibrary timestamp convention (matches
+			// UpdatedAt). Was .unix() (seconds); reconciled to .valueOf().
+			":now": moment().utc().valueOf(),
+		},
+	};
+	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.
+			log(
+				"incrementTemplateUseCount",
+				"TableNotFound",
+				"contentLibrary table not found — skipped",
+			);
+			return false;
+		}
+		if (error?.code === "ConditionalCheckFailedException") {
+			// TemplateId references no existing template — skip rather than
+			// create a phantom row. Not an error; continue the stream handler.
+			log("incrementTemplateUseCount", "NoSuchTemplate", { templateId });
+			return false;
+		}
+		// Anything else is genuinely unexpected — surface it.
+		log("incrementTemplateUseCount", "Error", error);
+		throw error;
+	}
+};
+
+module.exports = {
+	// Story A
+	isHqLocked,
+	// Story B
+	findCopiesByHqSourceId,
+	fanOutHqSource,
+	writeCopiesForTargets,
+	syncHqTargets,
+	propagateHqEdit,
+	cascadeHqRetract,
+	incrementTemplateUseCount,
+	// Exposed for tests and other entities that want to extend the protected list
+	DEFAULT_PROTECTED_FIELDS,
+};