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

package/helper/hqPublishing.js

@@ -11,13 +11,42 @@
  * Story coverage:
  * - **Story A (PC-1443)** — `isHqLocked` (lock guard for community-copy mutations).
  * - **Story B (PC-1444)** — adds `findCopiesByHqSourceId`, `fanOutHqSource`,
- *   `propagateHqEdit`, `cascadeHqRetract`, and `incrementTemplateUseCount`
- *   (these will appear as additional exports here).
+ *   `propagateHqEdit`, `cascadeHqRetract`, and `incrementTemplateUseCount`.
  *
- * If this file grows beyond ~200 lines or develops sub-themes, refactor to a
+ * 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**.
@@ -40,6 +69,281 @@
  */
 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();
+
+	// 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` 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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@plusscommunities/pluss-core-aws",
-	"version": "2.0.25-beta.0",
+	"version": "2.0.25-beta.2",
 	"description": "Core extension package for Pluss Communities platform",
 	"scripts": {
 		"betapatch": "npm version prepatch --preid=beta",