@adobe/spacecat-shared-data-access 3.63.0 → 3.64.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [@adobe/spacecat-shared-data-access-v3.64.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.63.0...@adobe/spacecat-shared-data-access-v3.64.0) (2026-05-15)
+
+### Features
+
+* strict schema for data.issues[] with per-issue lifecycle fields       ([#1594](https://github.com/adobe/spacecat-shared/issues/1594)) ([d101db4](https://github.com/adobe/spacecat-shared/commit/d101db4e6407cfe9cbb742d54b500439cf62b64f))
+
 ## [@adobe/spacecat-shared-data-access-v3.63.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.62.0...@adobe/spacecat-shared-data-access-v3.63.0) (2026-05-14)
 
 ### Features

package/package.json

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

package/src/models/suggestion/index.js

@@ -20,3 +20,11 @@ export {
 
 // Export DATA_SCHEMAS for api-service to reference
 export const { DATA_SCHEMAS } = Suggestion;
+
+// Re-export per-issue lifecycle constants so consumers (audit-worker, autofix-worker,
+// api-service, Mystique) can validate per-issue values without duplicating enum lists.
+export {
+  CWV_METRIC_TYPES,
+  ISSUE_STATUSES,
+  ISSUE_SKIP_REASONS,
+} from './suggestion.data-schemas.js';

package/src/models/suggestion/suggestion.data-schemas.js

@@ -26,6 +26,85 @@
 import Joi from 'joi';
 import { OPPORTUNITY_TYPES } from '@adobe/spacecat-shared-utils';
 
+/**
+ * Status and skip-reason values for per-issue lifecycle inside `data.issues[]`.
+ *
+ * Exported for consumers that need to construct or validate per-issue values
+ * (audit-worker, autofix-worker, api-service controllers, Mystique).
+ *
+ * Duplicated from `Suggestion.STATUSES` / `Suggestion.SKIP_REASONS` (suggestion.model.js)
+ * to avoid a circular import — the model already imports DATA_SCHEMAS from this file.
+ * Keep in sync if either set ever changes.
+ */
+export const ISSUE_STATUSES = [
+  'NEW',
+  'APPROVED',
+  'IN_PROGRESS',
+  'SKIPPED',
+  'FIXED',
+  'ERROR',
+  'OUTDATED',
+  'PENDING_VALIDATION',
+  'REJECTED',
+];
+
+export const ISSUE_SKIP_REASONS = [
+  'ALREADY_IMPLEMENTED',
+  'INACCURATE_OR_INCOMPLETE',
+  'TOO_RISKY',
+  'NO_REASON',
+  'OTHER',
+];
+
+/**
+ * Allowed CWV metric types for `data.issues[].type`.
+ * Exported so audit-worker / Mystique / api-service can reuse the same source of truth.
+ */
+export const CWV_METRIC_TYPES = ['lcp', 'cls', 'inp'];
+
+/**
+ * Strict per-issue schema for `data.issues[]` on CWV suggestions.
+ *
+ * All fields are optional initially so existing prod rows (issues without `id` / `type` /
+ * `status`) keep validating. Tighten to required after a backfill populates `id` and `type`
+ * on every existing issue.
+ *
+ * Field ownership:
+ * - `id`, `type`, `value`, `title`, `cwvValue`, `patchContent`, `isCodeChangeAvailable`,
+ *   initial `status: 'NEW'` — written by Mystique (guidance + code-fix tasks).
+ * - `status` transitions (APPROVED/REJECTED/SKIPPED/IN_PROGRESS) — written by api-service
+ *   via the existing PATCH /suggestions/:id endpoint (UI does read-modify-write of the
+ *   whole `data` payload).
+ * - `status: FIXED | ERROR` — written by autofix-worker after PR creation.
+ * - `status: OUTDATED` — written by audit-worker `handleOutdatedSuggestions` on re-audit.
+ * - `fixEntityId` — written by autofix-worker (or Mystique `_create_fix_entity`).
+ * - `jiraLink` — written by whichever service files the Jira ticket (today: UI or api-service).
+ * - `skipReason`, `skipDetail` — written by api-service when `status` transitions to SKIPPED.
+ */
+const CWV_ISSUE_SCHEMA = Joi.object({
+  // Identity
+  id: Joi.string().optional(),
+
+  // Semantic
+  type: Joi.string().valid(...CWV_METRIC_TYPES).optional(),
+  title: Joi.string().optional(),
+  value: Joi.string().optional(),
+  cwvValue: Joi.number().optional(),
+
+  // Patch
+  patchContent: Joi.string().allow('').optional(),
+  isCodeChangeAvailable: Joi.boolean().optional(),
+
+  // Lifecycle
+  status: Joi.string().valid(...ISSUE_STATUSES).optional(),
+  skipReason: Joi.string().valid(...ISSUE_SKIP_REASONS).optional(),
+  skipDetail: Joi.string().max(1000).optional(),
+
+  // Linkage
+  jiraLink: Joi.string().uri().allow(null).optional(),
+  fixEntityId: Joi.string().uuid().optional(),
+}).unknown(true);
+
 /**
  * Custom Joi validator that accepts malformed HTTP/HTTPS URLs and relative paths
  * while rejecting dangerous URI schemes (javascript:, data:, blob:, etc.).
@@ -148,22 +227,26 @@ export const DATA_SCHEMAS = {
       url: Joi.string().uri().optional(),
       pageviews: Joi.number().optional(),
       organic: Joi.number().optional(),
+      // RUM metrics are nullable in practice. INP requires user interaction events,
+      // so devices/pages without interactions report `inp: null`. The *Count fields
+      // similarly are null when the source RUM bundle has no sample for that metric.
+      // Mirror the existing `.allow(null)` already on lcp/ttfb/cls.
       metrics: Joi.array().items(
         Joi.object({
           deviceType: Joi.string().optional(),
-          pageviews: Joi.number().optional(),
-          clsCount: Joi.number().optional(),
-          ttfbCount: Joi.number().optional(),
+          pageviews: Joi.number().allow(null).optional(),
+          clsCount: Joi.number().allow(null).optional(),
+          ttfbCount: Joi.number().allow(null).optional(),
           lcp: Joi.number().allow(null).optional(),
-          inpCount: Joi.number().optional(),
-          inp: Joi.number().optional(),
+          inpCount: Joi.number().allow(null).optional(),
+          inp: Joi.number().allow(null).optional(),
           ttfb: Joi.number().allow(null).optional(),
           cls: Joi.number().allow(null).optional(),
-          lcpCount: Joi.number().optional(),
-          organic: Joi.number().optional(),
+          lcpCount: Joi.number().allow(null).optional(),
+          organic: Joi.number().allow(null).optional(),
         }).unknown(true),
       ).required(),
-      issues: Joi.array().items(Joi.object()).optional().default([]),
+      issues: Joi.array().items(CWV_ISSUE_SCHEMA).optional().default([]),
       jiraLink: Joi.string().uri().allow(null).optional(),
       aggregationKey: Joi.string().allow(null).optional(),
     }).unknown(true),