@adobe/spacecat-shared-data-access 4.3.1 → 4.5.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.5.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.4.0...@adobe/spacecat-shared-data-access-v4.5.0) (2026-07-10)
+
+### Features
+
+* **data-access:** generalize deriveSuggestionStatus bubble-up + classifyStatus (SITES-47285) ([#1797](https://github.com/adobe/spacecat-shared/issues/1797)) ([732f647](https://github.com/adobe/spacecat-shared/commit/732f647724d1922f70d32b42fedd46824b0c1bde))
+
+## [@adobe/spacecat-shared-data-access-v4.4.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.3.1...@adobe/spacecat-shared-data-access-v4.4.0) (2026-07-09)
+
+### Features
+
+* **fix-entity:** add allByOpportunityIds for site-wide fix queries ([#1792](https://github.com/adobe/spacecat-shared/issues/1792)) ([25309bf](https://github.com/adobe/spacecat-shared/commit/25309bff4be7d90c0f7cdbf854c48a20adfd3e57))
+
 ## [@adobe/spacecat-shared-data-access-v4.3.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.3.0...@adobe/spacecat-shared-data-access-v4.3.1) (2026-07-09)
 
 ### Bug Fixes

package/CLAUDE.md

@@ -237,7 +237,8 @@ Rollout intent: ship `warn` to surface today's illegal transitions in logs for
 **APIs** (exported from the package root):
 - `setStatus(value)` / `transitionStatus(to)` on `Suggestion` and `FixEntity` — both guard the transition; `transitionStatus` is the intention-revealing alias for new code.
 - `isAllowedFixTransition(from, to)` / `isAllowedSuggestionTransition(from, to)` + the `FIX_ENTITY_TRANSITIONS` / `SUGGESTION_TRANSITIONS` tables (a null/undefined `from` means entity creation).
-- `deriveSuggestionStatus(fixes, issues = [])` — derives a Suggestion status from its fix entities. **Implements the non-CWV 1:1 bubble-up only** (`DEPLOYED`/`PUBLISHED`→`FIXED`, `FAILED`→`ERROR`, `PENDING`→`IN_PROGRESS`, `ROLLED_BACK`→`SKIPPED`; severity-collapses for >1 fix). **Throws** if a non-empty `issues` array is passed — the CWV multi-issue bubble-up is deferred (SITES-47285), because the per-issue codefix vocabulary (`PATCH_*`/`GUIDANCE_GENERATED`, written by mystique into the overloaded `issue.status` field) is not yet reconciled with the JS `ISSUE_STATUSES` enum.
+- `deriveSuggestionStatus(outcomes, issues = [], currentStatus = null)` — derives a Suggestion status from a per-suggestion list of **outcome signals**. Each entry is a FixEntity, `{status}`, or a status string from **either** vocabulary: FixEntity statuses (`DEPLOYED`/`PUBLISHED`→FIXED, `FAILED`→ERROR, `PENDING`→IN_PROGRESS, `ROLLED_BACK`/`REJECTED`→SKIPPED) **or** explicit Suggestion-status outcomes a handler asserts for no-fix cases (e.g. consciously skipped → `'SKIPPED'`, not-actionable → `'NEW'`). Signals are classified via `classifyStatus` and collapsed **first-match-wins by severity: ERROR > IN_PROGRESS > FIXED > SKIPPED**; all-NEUTRAL (e.g. only `NEW`) → `NEW`; no recognized signals → `currentStatus` (default null, so a derive call never clobbers a status set elsewhere). **Throws** if a non-empty `issues` array is passed — the CWV multi-issue bubble-up is deferred (SITES-47285): the per-issue codefix vocabulary (`PATCH_*`/`GUIDANCE_GENERATED`, written by mystique into the overloaded `issue.status` field) is not yet reconciled with the JS layer.
+- `classifyStatus(token)` — maps a fix- or suggestion-status token to its severity class (`ERROR`/`IN_PROGRESS`/`FIXED`/`SKIPPED`/`NEUTRAL`) or `null`. The shared building block behind the bubble-up; consumers building custom collapses should reuse it rather than re-encode the mapping.
 
 Notes: the `FixEntity` table is the canonical one from the ADR; the `Suggestion`
 table is intentionally **permissive in V1** (tune it from the warn-log findings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "4.3.1",
+  "version": "4.5.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/fix-entity/fix-entity.collection.js

@@ -15,6 +15,11 @@ import ValidationError from '../../errors/validation.error.js';
 import { guardId, guardArray, guardString } from '../../util/guards.js';
 import { resolveUpdates } from '../../util/util.js';
 
+// PostgREST GET requests serialize IN-filters into the URL, so large ID lists must be
+// chunked to stay well under the ~8KB URL length limit (see batchGetByKeys / llmo-brand-presence
+// for the same pattern elsewhere in this package).
+const IN_FILTER_CHUNK_SIZE = 50;
+
 /**
  * FixEntityCollection - A collection class responsible for managing FixEntities.
  * Extends the BaseCollection to provide specific methods for interacting with
@@ -226,6 +231,49 @@ class FixEntityCollection extends BaseCollection {
     }
   }
 
+  /**
+   * Gets all fixes across a set of opportunities (e.g. every opportunity for a site),
+   * by filtering on opportunityId IN (...). Chunks the IN-filter to stay under
+   * PostgREST's URL length limit.
+   *
+   * @async
+   * @param {string[]} opportunityIds - The IDs of the opportunities.
+   * @returns {Promise<FixEntity[]>} - A promise that resolves to an array of FixEntity models.
+   * @throws {DataAccessError} - Throws an error if the query fails.
+   * @throws {ValidationError} - Throws an error if opportunityIds is not an array of strings.
+   */
+  async allByOpportunityIds(opportunityIds) {
+    guardArray('opportunityIds', opportunityIds, 'FixEntityCollection', 'string');
+
+    if (opportunityIds.length === 0) {
+      return [];
+    }
+
+    try {
+      const uniqueIds = [...new Set(opportunityIds)];
+
+      const chunks = [];
+      for (let i = 0; i < uniqueIds.length; i += IN_FILTER_CHUNK_SIZE) {
+        chunks.push(uniqueIds.slice(i, i + IN_FILTER_CHUNK_SIZE));
+      }
+
+      const results = await Promise.all(
+        chunks.map((chunk) => this.all(
+          {},
+          { where: (attrs, op) => op.in(attrs.opportunityId, chunk) },
+        )),
+      );
+
+      return results.flat();
+    } catch (error) {
+      if (error instanceof DataAccessError) {
+        throw error;
+      }
+      this.log.error('Failed to get all fixes by opportunity IDs', error);
+      throw new DataAccessError('Failed to get all fixes by opportunity IDs', this, error);
+    }
+  }
+
   async #buildFixesWithSuggestions(fixEntitySuggestions) {
     if (fixEntitySuggestions.length === 0) {
       return [];

package/src/models/suggestion/derive-status.js

@@ -11,10 +11,10 @@
  */
 
 /**
- * Suggestion + FixEntity status literals.
+ * Suggestion status literals (return values).
  *
- * Duplicated from the model enums to keep this a dependency-light pure module.
- * Keep in sync if either enum changes. (Same pattern as suggestion.data-schemas.js.)
+ * Duplicated from the model enum to keep this a dependency-light pure module.
+ * Keep in sync if the enum changes. (Same pattern as suggestion.data-schemas.js.)
  */
 const SUGGESTION = {
   NEW: 'NEW',
@@ -24,89 +24,135 @@ const SUGGESTION = {
   ERROR: 'ERROR',
 };
 
-const FIX = {
-  PENDING: 'PENDING',
-  DEPLOYED: 'DEPLOYED',
-  PUBLISHED: 'PUBLISHED',
-  FAILED: 'FAILED',
-  ROLLED_BACK: 'ROLLED_BACK',
+/**
+ * Severity classes for the bubble-up (ADR adobe/mysticat-architecture#174).
+ * Highest severity first-match-wins; NEUTRAL never contributes to severity
+ * (a suggestion whose only signals are NEUTRAL resolves to NEW).
+ */
+const CLASS = {
+  ERROR: 'ERROR',
+  IN_PROGRESS: 'IN_PROGRESS',
+  FIXED: 'FIXED',
+  SKIPPED: 'SKIPPED',
+  NEUTRAL: 'NEUTRAL',
+};
+
+/**
+ * Maps a status token to its severity class. Covers BOTH vocabularies so a
+ * caller can pass FixEntity statuses (DEPLOYED/FAILED/PENDING/ROLLED_BACK/...)
+ * and/or explicit Suggestion-status outcomes (FIXED/ERROR/SKIPPED/NEW/...) for
+ * cases with no fix entity (e.g. a consciously-skipped or not-actionable
+ * suggestion). `REJECTED` collapses to SKIPPED in either vocabulary. Unknown
+ * tokens are ignored (null).
+ */
+const CLASS_BY_STATUS = {
+  // ERROR-class
+  FAILED: CLASS.ERROR, // fix
+  ERROR: CLASS.ERROR, // suggestion
+  // IN_PROGRESS-class
+  PENDING: CLASS.IN_PROGRESS, // fix
+  IN_PROGRESS: CLASS.IN_PROGRESS, // suggestion
+  // FIXED-class
+  DEPLOYED: CLASS.FIXED, // fix
+  PUBLISHED: CLASS.FIXED, // fix
+  FIXED: CLASS.FIXED, // suggestion
+  // SKIPPED-class
+  ROLLED_BACK: CLASS.SKIPPED, // fix
+  REJECTED: CLASS.SKIPPED, // fix / suggestion
+  SKIPPED: CLASS.SKIPPED, // suggestion
+  // NEUTRAL — present but non-severity; all-NEUTRAL resolves to NEW
+  NEW: CLASS.NEUTRAL,
+  OUTDATED: CLASS.NEUTRAL,
+  APPROVED: CLASS.NEUTRAL,
+  PENDING_VALIDATION: CLASS.NEUTRAL,
 };
 
 /**
- * Normalizes a fix entry to its status string. Accepts a FixEntity model
+ * Classifies a status token into its bubble-up severity class, or null if the
+ * token is unknown.
+ *
+ * @param {string|null|undefined} token
+ * @returns {'ERROR'|'IN_PROGRESS'|'FIXED'|'SKIPPED'|'NEUTRAL'|null}
+ */
+export const classifyStatus = (token) => (
+  Object.prototype.hasOwnProperty.call(CLASS_BY_STATUS, token)
+    ? CLASS_BY_STATUS[token]
+    : null
+);
+
+/**
+ * Normalizes an outcome entry to its status string. Accepts a FixEntity model
  * instance (`getStatus()`), a plain `{ status }` object, or a status string.
  */
-const toStatus = (fix) => {
-  if (typeof fix === 'string') {
-    return fix;
+const toStatus = (outcome) => {
+  if (typeof outcome === 'string') {
+    return outcome;
   }
-  if (fix && typeof fix.getStatus === 'function') {
-    return fix.getStatus();
+  if (outcome && typeof outcome.getStatus === 'function') {
+    return outcome.getStatus();
   }
-  return fix?.status;
+  return outcome?.status;
 };
 
 /**
- * Derives a Suggestion's status from its fix entities — the **non-CWV (1:1)**
- * bubble-up from ADR adobe/mysticat-architecture#174 §"Bubble-up rule (non-CWV
- * opportunities)":
+ * Derives a Suggestion's status from a per-suggestion list of outcome signals —
+ * the bubble-up from ADR adobe/mysticat-architecture#174.
  *
- *   FAILED      -> ERROR
- *   PENDING     -> IN_PROGRESS
- *   DEPLOYED    -> FIXED
- *   PUBLISHED   -> FIXED
- *   ROLLED_BACK -> SKIPPED
+ * Each `outcomes` entry is a FixEntity, a `{ status }` object, or a status
+ * string, from EITHER vocabulary:
+ *  - FixEntity statuses: DEPLOYED/PUBLISHED -> FIXED, FAILED -> ERROR,
+ *    PENDING -> IN_PROGRESS, ROLLED_BACK/REJECTED -> SKIPPED.
+ *  - explicit Suggestion-status outcomes for no-fix cases a handler asserts
+ *    (e.g. a consciously skipped suggestion -> 'SKIPPED', a not-actionable one
+ *    -> 'NEW').
  *
- * For a single fix this is exactly the ADR map. For multiple fixes it collapses
- * by severity (ERROR > IN_PROGRESS > FIXED > SKIPPED) so partial failure wins —
- * consistent with the CWV severity ordering. `Fix.REJECTED` is intentionally
- * absent: it is not in `FixEntity.STATUSES` (see SITES-47076).
+ * Signals are classified (`classifyStatus`) and collapsed **first-match-wins by
+ * severity**: ERROR > IN_PROGRESS > FIXED > SKIPPED. If signals are present but
+ * all NEUTRAL (e.g. only 'NEW') the result is NEW. If there are no recognized
+ * signals (empty / all-null / all-unknown) the result is `currentStatus`
+ * (default null), so a derive call never clobbers a status set elsewhere.
  *
  * The **CWV multi-issue** bubble-up is deliberately NOT implemented here: the
- * ADR's per-issue vocabulary (`cwvIssueStatus` = PATCH_GENERATED / GUIDANCE_*
- * / PATCH_FAILED_*) does not match the data layer (mystique writes those into
- * the overloaded per-issue `status` field; the JS `ISSUE_STATUSES` enum lists
- * only Suggestion statuses). Reconciling that is a follow-up sub-task,
- * SITES-47285. Passing a non-empty `issues` argument throws to prevent a caller
- * from silently receiving an unimplemented CWV result.
+ * per-issue vocabulary (mystique's cwvIssueStatus = PATCH_GENERATED /
+ * GUIDANCE_* / PATCH_FAILED_*) is not yet reconciled with the JS layer
+ * (SITES-47285). Passing a non-empty `issues` argument throws to prevent a
+ * caller from silently receiving an unimplemented CWV result.
  *
- * @param {Array<object|string>} fixes - fix entities / `{status}` / status strings
+ * @param {Array<object|string>} outcomes - fix entities / `{status}` / status strings
  * @param {Array<object>} [issues] - CWV per-issue data; MUST be empty for now
- * @param {string|null} [currentStatus] - the Suggestion's current status, returned as the
- *   fallback when nothing is derivable (no fixes / all-null / no matching rule) so a derive
- *   call never clobbers a status set elsewhere. Defaults to null (prior behavior).
- * @returns {string|null} derived Suggestion status, or `currentStatus` when nothing is derivable
+ * @param {string|null} [currentStatus] - fallback when nothing is derivable
+ * @returns {string|null} derived Suggestion status, or `currentStatus`
  * @throws {Error} if a non-empty `issues` array is supplied (CWV deferred)
  */
-export const deriveSuggestionStatus = (fixes, issues = [], currentStatus = null) => {
+export const deriveSuggestionStatus = (outcomes, issues = [], currentStatus = null) => {
   if (Array.isArray(issues) && issues.length > 0) {
     throw new Error('deriveSuggestionStatus: CWV multi-issue bubble-up is not yet implemented (deferred to SITES-47285)');
   }
 
-  if (!Array.isArray(fixes) || fixes.length === 0) {
+  if (!Array.isArray(outcomes)) {
     return currentStatus;
   }
 
-  // Drop null/undefined entries (e.g. a sparse junction result) so one malformed
-  // entry cannot nullify an otherwise well-defined derivation; degrades to the
-  // same "no fixes" behavior as an empty array.
-  const statuses = fixes.map(toStatus).filter((s) => s != null);
-  if (statuses.length === 0) {
+  // Classify each signal; drop unknown/null so one malformed entry cannot
+  // nullify an otherwise well-defined derivation.
+  const classes = outcomes.map(toStatus).map(classifyStatus).filter((c) => c != null);
+  if (classes.length === 0) {
     return currentStatus;
   }
 
-  if (statuses.includes(FIX.FAILED)) {
+  if (classes.includes(CLASS.ERROR)) {
     return SUGGESTION.ERROR;
   }
-  if (statuses.includes(FIX.PENDING)) {
+  if (classes.includes(CLASS.IN_PROGRESS)) {
     return SUGGESTION.IN_PROGRESS;
   }
-  if (statuses.includes(FIX.DEPLOYED) || statuses.includes(FIX.PUBLISHED)) {
+  if (classes.includes(CLASS.FIXED)) {
     return SUGGESTION.FIXED;
   }
-  if (statuses.every((s) => s === FIX.ROLLED_BACK)) {
+  if (classes.includes(CLASS.SKIPPED)) {
     return SUGGESTION.SKIPPED;
   }
 
-  return currentStatus;
+  // signals present but all NEUTRAL (e.g. only NEW/OUTDATED)
+  return SUGGESTION.NEW;
 };

package/src/models/suggestion/index.d.ts

@@ -45,6 +45,10 @@ export declare function isAllowedSuggestionTransition(
   to: string,
 ): boolean;
 export declare function deriveSuggestionStatus(
-  fixes: Array<FixEntity | { status?: string } | string>,
+  outcomes: Array<FixEntity | { status?: string } | string>,
   issues?: Array<object>,
+  currentStatus?: string | null,
 ): string | null;
+export declare function classifyStatus(
+  token: string | null | undefined,
+): 'ERROR' | 'IN_PROGRESS' | 'FIXED' | 'SKIPPED' | 'NEUTRAL' | null;

package/src/models/suggestion/index.js

@@ -36,4 +36,4 @@ export {
   SUGGESTION_CREATE,
   isAllowedSuggestionTransition,
 } from './suggestion.transitions.js';
-export { deriveSuggestionStatus } from './derive-status.js';
+export { deriveSuggestionStatus, classifyStatus } from './derive-status.js';