@adobe/spacecat-shared-data-access 4.12.0 → 4.14.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v4.14.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.13.0...@adobe/spacecat-shared-data-access-v4.14.0) (2026-07-27)
+
+### Features
+
+* **data-access:** derive portable JSON Schema artifact for changeDetails v2 (SITES-47997) ([#1830](https://github.com/adobe/spacecat-shared/issues/1830)) ([02163de](https://github.com/adobe/spacecat-shared/commit/02163dea72d007678777b8341d0ded2b97fb56cf)), closes [#1828](https://github.com/adobe/spacecat-shared/issues/1828) [blocking-#4](https://github.com/adobe/blocking-/issues/4)
+
+## [@adobe/spacecat-shared-data-access-v4.13.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.12.0...@adobe/spacecat-shared-data-access-v4.13.0) (2026-07-23)
+
+### Features
+
+* **data-access:** list configuration versions via S3 object versioning ([#1839](https://github.com/adobe/spacecat-shared/issues/1839)) ([5dd66fc](https://github.com/adobe/spacecat-shared/commit/5dd66fc9aee60215ea4355395e280c66ae44dcb9))
+
 ## [@adobe/spacecat-shared-data-access-v4.12.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v4.11.0...@adobe/spacecat-shared-data-access-v4.12.0) (2026-07-23)
 
 ### Features

package/CLAUDE.md

@@ -277,6 +277,17 @@ validated "deploy action" record (who/when/what/which-pages/result) from ADR
     `CALL_STATUSES`, `APPLIED`, `CHANGE_RESULT_STATUSES`, `VERIFY_VERDICTS`,
     `SCHEMA_VERSION`, `DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES`). Kept on the model
     (not the barrel) to avoid collisions on these generic names.
+- **Portable JSON Schema artifact** (for the Python runtime, mystique). The Joi
+  schema is the single source of truth; a **JSON Schema is derived from it** and
+  shipped at `schemas/fix-entity-change-details.v2.schema.json` (draft-2019-09).
+  Regenerate with `npm run generate:schemas` (script:
+  `scripts/generate-change-details-schema.js`, uses `joi-to-json`); a unit test
+  fails CI if the committed artifact drifts from the Joi schema. mystique vendors
+  this file and validates against it. **Caveat:** JSON Schema captures
+  structure/enums/required/patterns only — the cross-field invariants
+  (`changeResults`↔`target.changes` key-match, `applied:ALL` completeness,
+  `deployResponsePayload` 4 KB cap) are Joi `.custom()` rules and are NOT in the
+  artifact; a consumer needing them must port those checks.
 - **Not yet done** (tracked on SITES-47997): the `publishedBy` column +
   `executedBy/At` → `deployedBy/At` rename (dual-write, needs a companion
   mysticat-data-service migration), and gating the `DEPLOYED`/`PUBLISHED`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "4.12.0",
+  "version": "4.14.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -19,7 +19,8 @@
     "test:debug:grep": "mocha --inspect-brk --require ./test/setup-env.js --grep",
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "clean": "rm -rf package-lock.json node_modules"
+    "clean": "rm -rf package-lock.json node_modules",
+    "generate:schemas": "node scripts/generate-change-details-schema.js"
   },
   "mocha": {
     "require": "test/setup-env.js",
@@ -42,9 +43,9 @@
   "dependencies": {
     "@adobe/fetch": "^4.2.3",
     "@adobe/spacecat-shared-utils": "1.105.0",
-    "@supabase/postgrest-js": "2.106.2",
     "@aws-sdk/client-s3": "^3.940.0",
     "@smithy/util-retry": "^4.0.0",
+    "@supabase/postgrest-js": "2.106.2",
     "@types/joi": "17.2.3",
     "aws-xray-sdk": "3.12.0",
     "joi": "18.2.1",
@@ -54,6 +55,7 @@
     "chai": "6.2.2",
     "chai-as-promised": "8.0.2",
     "electrodb": "3.9.0",
+    "joi-to-json": "^5.0.5",
     "nock": "14.0.15",
     "sinon": "22.0.0",
     "sinon-chai": "4.0.1"

package/schemas/fix-entity-change-details.v2.schema.json

@@ -0,0 +1,268 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "$id": "https://ns.adobe.com/spacecat/fix-entity/change-details/v2",
+  "title": "FixEntity changeDetails v2",
+  "description": "Canonical v2 deploy-action record for FixEntity.changeDetails (SITES-47997, ADR adobe/mysticat-architecture#200). GENERATED from the Joi source of truth (changeDetailsV2Schema in spacecat-shared-data-access) — DO NOT EDIT BY HAND; run `npm run generate:schemas -w packages/spacecat-shared-data-access`. Structure/enums/required/patterns only: the cross-field invariants (changeResults<->target.changes key-match, applied:ALL completeness, deployResponsePayload 4KB cap) are Joi-enforced and NOT expressible in JSON Schema.",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "const": 2
+    },
+    "surface": {
+      "type": "string",
+      "enum": [
+        "ASO",
+        "AUTHOR_PUBLISH",
+        "GIT_MERGE",
+        "SYSTEM"
+      ]
+    },
+    "actorType": {
+      "type": "string",
+      "enum": [
+        "IMS_USER",
+        "SERVICE",
+        "GITHUB",
+        "DETECTOR",
+        "UNKNOWN"
+      ]
+    },
+    "target": {
+      "type": "object",
+      "properties": {
+        "system": {
+          "type": "string"
+        },
+        "changeType": {
+          "type": "string"
+        },
+        "siteId": {
+          "type": "string"
+        },
+        "pageId": {
+          "type": "string"
+        },
+        "documentPath": {
+          "type": "string"
+        },
+        "detectedPageAuthorUrl": {
+          "type": "string"
+        },
+        "changes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "properties": {
+              "targetPath": {
+                "type": "string"
+              },
+              "property": {
+                "type": "string"
+              },
+              "intendedValue": {
+                "type": [
+                  "array",
+                  "boolean",
+                  "number",
+                  "object",
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "required": [
+              "targetPath",
+              "property",
+              "intendedValue"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "required": [
+        "changeType",
+        "changes"
+      ],
+      "additionalProperties": false
+    },
+    "result": {
+      "type": "object",
+      "properties": {
+        "callStatus": {
+          "type": "string",
+          "enum": [
+            "success",
+            "no_op",
+            "client_error",
+            "server_error",
+            "timeout"
+          ]
+        },
+        "applied": {
+          "type": "string",
+          "enum": [
+            "ALL",
+            "PARTIAL",
+            "NONE"
+          ]
+        },
+        "deployResponsePayload": {
+          "type": [
+            "array",
+            "boolean",
+            "number",
+            "object",
+            "string",
+            "null"
+          ],
+          "description": "Raw deploy/apply API response (body + status + relevant headers). MUST be <= 4096 bytes at the write chokepoint; larger payloads must be hashed into deployResponseSha256 and truncated. Size cap enforced by the Joi validator, not by this JSON Schema."
+        },
+        "deployResponseSha256": {
+          "type": "string",
+          "pattern": "^[a-fA-F0-9]{64}$"
+        },
+        "changeResults": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "targetPath": {
+                "type": "string"
+              },
+              "property": {
+                "type": "string"
+              },
+              "previousValue": {
+                "type": [
+                  "array",
+                  "boolean",
+                  "number",
+                  "object",
+                  "string",
+                  "null"
+                ]
+              },
+              "appliedValue": {
+                "type": [
+                  "array",
+                  "boolean",
+                  "number",
+                  "object",
+                  "string",
+                  "null"
+                ]
+              },
+              "status": {
+                "type": "string",
+                "enum": [
+                  "applied",
+                  "unchanged",
+                  "failed"
+                ]
+              }
+            },
+            "required": [
+              "targetPath",
+              "property",
+              "status"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "preVerify": {
+          "type": "object",
+          "properties": {
+            "verdict": {
+              "type": "string",
+              "enum": [
+                "verified",
+                "rejected",
+                "inconclusive",
+                "verify_failed"
+              ]
+            },
+            "reasonCode": {
+              "type": "string"
+            },
+            "evidence": {
+              "type": [
+                "array",
+                "boolean",
+                "number",
+                "object",
+                "string",
+                "null"
+              ]
+            },
+            "preVerifiedAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          "required": [
+            "verdict"
+          ],
+          "additionalProperties": false
+        },
+        "postVerify": {
+          "type": "object",
+          "properties": {
+            "verdict": {
+              "type": "string",
+              "enum": [
+                "verified",
+                "rejected",
+                "inconclusive",
+                "verify_failed"
+              ]
+            },
+            "reasonCode": {
+              "type": "string"
+            },
+            "evidence": {
+              "type": [
+                "array",
+                "boolean",
+                "number",
+                "object",
+                "string",
+                "null"
+              ]
+            },
+            "revert": {
+              "type": [
+                "array",
+                "boolean",
+                "number",
+                "object",
+                "string",
+                "null"
+              ]
+            },
+            "postVerifiedAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          "required": [
+            "verdict"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "callStatus",
+        "applied"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "surface",
+    "actorType",
+    "target"
+  ],
+  "additionalProperties": false
+}

package/src/models/configuration/configuration.collection.js

@@ -12,6 +12,8 @@
 
 import {
   GetObjectCommand,
+  HeadObjectCommand,
+  ListObjectVersionsCommand,
   PutObjectCommand,
 } from '@aws-sdk/client-s3';
 
@@ -22,6 +24,12 @@ import { checkConfiguration } from './configuration.schema.js';
 
 const S3_CONFIG_KEY = 'config/spacecat/global-config.json';
 
+// Cap on concurrent HeadObject calls during version enrichment. Bounds the
+// fan-out regardless of page size so a large `listVersions({ detail: true })`
+// can't fire hundreds of concurrent requests in one tick (socket-pool
+// exhaustion / S3 503 SlowDown in Lambda).
+const ENRICH_CONCURRENCY = 25;
+
 /**
  * ConfigurationCollection - A standalone collection class for managing Configuration entities.
  * Unlike other collections, this uses S3 instead of PostgREST.
@@ -108,6 +116,17 @@ class ConfigurationCollection {
         Key: S3_CONFIG_KEY,
         Body: JSON.stringify(configData),
         ContentType: 'application/json',
+        // Stamp the audit fields into S3 user-metadata so `listVersions` can
+        // surface who/when for each version via a cheap metadata-only HeadObject
+        // (no full-body download). Keys are lowercased by S3. We stamp the
+        // already-normalized `configData` values (updatedBy defaults to 'system'
+        // above, updatedAt is the ISO `now`) — both are guaranteed non-empty
+        // strings, so no literal "undefined"/"null" can ever be persisted into
+        // the immutable per-version metadata.
+        Metadata: {
+          updatedby: configData.updatedBy,
+          updatedat: configData.updatedAt,
+        },
       });
 
       const response = await this.s3Client.send(command);
@@ -205,6 +224,155 @@ class ConfigurationCollection {
       throw new DataAccessError(message, this, error);
     }
   }
+
+  /**
+   * Enriches a version row with `updatedBy`/`updatedAt` read from the object's
+   * S3 user-metadata via a metadata-only HeadObject (no body download). Versions
+   * written before user-metadata was introduced resolve to null so one missing
+   * row never fails the whole page.
+   *
+   * A HeadObject on a version we *just listed* should only fail for a systemic
+   * reason (missing `s3:GetObjectVersion` IAM, throttling) — NOT the expected
+   * "object gone" cases. We still degrade to null (enrichment is best-effort and
+   * must not sink the primary listing), but we log such failures at `error` so a
+   * page that comes back all-null reads as an outage, not as "old versions".
+   * @private
+   * @param {Object} version - The base version row from `listVersions`.
+   * @returns {Promise<Object>} The version row with `updatedBy`/`updatedAt`.
+   */
+  async #enrichVersion(version) {
+    try {
+      const command = new HeadObjectCommand({
+        Bucket: this.s3Bucket,
+        Key: S3_CONFIG_KEY,
+        VersionId: version.versionId,
+      });
+      const response = await this.s3Client.send(command);
+      const metadata = response.Metadata || {};
+      return {
+        ...version,
+        updatedBy: metadata.updatedby || null,
+        updatedAt: metadata.updatedat || null,
+      };
+    } catch (error) {
+      // NoSuchKey/NoSuchVersion = the version was reaped between list and head;
+      // benign. Anything else (AccessDenied, SlowDown, network) is systemic.
+      const benign = error.name === 'NoSuchKey' || error.name === 'NoSuchVersion';
+      const logAt = benign ? this.log.warn : this.log.error;
+      logAt.call(
+        this.log,
+        `Failed to read metadata for configuration version ${version.versionId} `
+        + `(${error.name || 'Error'}): ${error.message}`,
+      );
+      return { ...version, updatedBy: null, updatedAt: null };
+    }
+  }
+
+  /**
+   * Enriches version rows in bounded-concurrency batches of `ENRICH_CONCURRENCY`
+   * so the HeadObject fan-out stays capped regardless of page size.
+   * @private
+   * @param {Array<Object>} rawVersions - The base version rows.
+   * @returns {Promise<Array<Object>>} The enriched rows, in order.
+   */
+  async #enrichVersions(rawVersions) {
+    const enriched = [];
+    for (let i = 0; i < rawVersions.length; i += ENRICH_CONCURRENCY) {
+      const batch = rawVersions.slice(i, i + ENRICH_CONCURRENCY);
+      // Serialize batches to bound concurrency; within a batch calls run in parallel.
+      // eslint-disable-next-line no-await-in-loop
+      const results = await Promise.all(batch.map((version) => this.#enrichVersion(version)));
+      enriched.push(...results);
+    }
+    return enriched;
+  }
+
+  /**
+   * Lists configuration versions from S3 object versioning, newest first.
+   *
+   * S3 `ListObjectVersions` returns version-level metadata only (VersionId,
+   * LastModified, IsLatest, Size); the human-facing `updatedBy`/`updatedAt`
+   * live inside each version's body. When `detail` is true, each row is
+   * enriched with a parallel metadata-only HeadObject (see `#enrichVersion`) —
+   * cheap because it never downloads the (multi-MB) config body.
+   *
+   * Callers MUST page on `isTruncated` + the returned markers, NOT on
+   * `versions.length`: `MaxKeys` bounds the raw S3 result (versions + any delete
+   * markers + sibling-prefix keys) before we filter to the config object, so a
+   * page can legitimately return fewer rows than `limit` — or even zero — while
+   * `isTruncated` is true. (In practice the global config is PUT-only and never
+   * deleted, so delete markers do not occur today.)
+   *
+   * @param {Object} [options] - Listing options.
+   * @param {number} [options.limit=25] - Max versions to return (coerced to an
+   *   integer and clamped to [1, 1000]). Enrichment concurrency is bounded
+   *   separately by `ENRICH_CONCURRENCY`, independent of this page size.
+   * @param {string} [options.keyMarker] - S3 KeyMarker for pagination.
+   * @param {string} [options.versionIdMarker] - S3 VersionIdMarker for pagination.
+   * @param {boolean} [options.detail=true] - Enrich rows with updatedBy/updatedAt.
+   * @returns {Promise<{versions: Array<Object>, isTruncated: boolean,
+   *   nextKeyMarker: (string|null), nextVersionIdMarker: (string|null)}>}
+   * @throws {DataAccessError} If S3 is not configured or the operation fails.
+   */
+  async listVersions({
+    limit = 25,
+    keyMarker,
+    versionIdMarker,
+    detail = true,
+  } = {}) {
+    this.#requireS3();
+
+    // Coerce + clamp: an unvalidated limit (NaN/negative/huge from a query
+    // string) would otherwise flow straight to S3 MaxKeys. (The HeadObject
+    // fan-out is bounded separately by #enrichVersions.)
+    const parsedLimit = Number.parseInt(limit, 10);
+    const maxKeys = Number.isInteger(parsedLimit)
+      ? Math.min(Math.max(parsedLimit, 1), 1000)
+      : 25;
+
+    try {
+      const command = new ListObjectVersionsCommand({
+        Bucket: this.s3Bucket,
+        Prefix: S3_CONFIG_KEY,
+        MaxKeys: maxKeys,
+        ...(keyMarker ? { KeyMarker: keyMarker } : {}),
+        ...(versionIdMarker ? { VersionIdMarker: versionIdMarker } : {}),
+      });
+
+      const response = await this.s3Client.send(command);
+
+      // Defensive: the prefix is an exact key, but a shared prefix could in
+      // theory match sibling keys — keep only the config object's versions.
+      const rawVersions = (response.Versions || [])
+        .filter((version) => version.Key === S3_CONFIG_KEY)
+        .map((version) => ({
+          versionId: version.VersionId,
+          lastModified: version.LastModified instanceof Date
+            ? version.LastModified.toISOString()
+            : version.LastModified,
+          isLatest: Boolean(version.IsLatest),
+          size: version.Size,
+        }));
+
+      const versions = detail
+        ? await this.#enrichVersions(rawVersions)
+        : rawVersions;
+
+      return {
+        versions,
+        isTruncated: Boolean(response.IsTruncated),
+        nextKeyMarker: response.NextKeyMarker || null,
+        nextVersionIdMarker: response.NextVersionIdMarker || null,
+      };
+    } catch (error) {
+      if (error instanceof DataAccessError) {
+        throw error;
+      }
+      const message = `Failed to list configuration versions from S3: ${error.message}`;
+      this.log.error(message, error);
+      throw new DataAccessError(message, this, error);
+    }
+  }
 }
 
 export default ConfigurationCollection;

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

@@ -60,8 +60,30 @@ export interface Configuration {
   updateQueues(queues: object): void;
 }
 
+export interface ConfigurationVersion {
+  versionId: string;
+  lastModified: string;
+  isLatest: boolean;
+  size: number;
+  updatedBy?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface ConfigurationVersionsPage {
+  versions: ConfigurationVersion[];
+  isTruncated: boolean;
+  nextKeyMarker: string | null;
+  nextVersionIdMarker: string | null;
+}
+
 export interface ConfigurationCollection {
   create(data: object): Promise<Configuration>;
   findByVersion(version: string): Promise<Configuration | null>;
   findLatest(): Promise<Configuration | null>;
+  listVersions(options?: {
+    limit?: number;
+    keyMarker?: string;
+    versionIdMarker?: string;
+    detail?: boolean;
+  }): Promise<ConfigurationVersionsPage>;
 }

package/src/models/fix-entity/change-details.schema.js

@@ -157,10 +157,17 @@ const resultSchema = Joi.object({
       return helpers.error('any.invalid');
     }
     return value;
-  }).messages({
-    'any.invalid': `result.deployResponsePayload exceeds ${DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES} bytes; hash it into deployResponseSha256 and truncate at the write chokepoint`,
-  }),
-  deployResponseSha256: Joi.string().pattern(/^[a-f0-9]{64}$/i),
+  })
+    // Carried into the derived JSON Schema so the size-cap caveat travels with
+    // the field for JSON-Schema-only (mystique) consumers — the cap itself is a
+    // Joi `.custom()` rule and is NOT expressible/enforced in JSON Schema.
+    .description(`Raw deploy/apply API response (body + status + relevant headers). MUST be <= ${DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES} bytes at the write chokepoint; larger payloads must be hashed into deployResponseSha256 and truncated. Size cap enforced by the Joi validator, not by this JSON Schema.`)
+    .messages({
+      'any.invalid': `result.deployResponsePayload exceeds ${DEPLOY_RESPONSE_PAYLOAD_MAX_BYTES} bytes; hash it into deployResponseSha256 and truncate at the write chokepoint`,
+    }),
+  // Explicit case ranges (not the /i flag) so the derived JSON Schema `pattern`
+  // stays flag-free and portable to Python's re-based validators.
+  deployResponseSha256: Joi.string().pattern(/^[a-fA-F0-9]{64}$/),
   changeResults: Joi.array().items(changeResultSchema),
   preVerify: preVerifySchema,
   postVerify: postVerifySchema,