@adobe/spacecat-shared-utils 1.113.0 → 1.115.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-utils-v1.115.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.114.0...@adobe/spacecat-shared-utils-v1.115.0) (2026-05-04)
+
+### Features
+
+* **strategy:** add type discriminator and experimentId for Atomic strategies | LLMO-4643 ([#1571](https://github.com/adobe/spacecat-shared/issues/1571)) ([0151ff5](https://github.com/adobe/spacecat-shared/commit/0151ff510f7643021e6c1ccf21298f6d3c07034b))
+
+## [@adobe/spacecat-shared-utils-v1.114.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.113.0...@adobe/spacecat-shared-utils-v1.114.0) (2026-05-04)
+
+### Features
+
+* **llmo-config:** fail-closed writeConfig validation (SITES-43238) ([#1574](https://github.com/adobe/spacecat-shared/issues/1574)) ([a177743](https://github.com/adobe/spacecat-shared/commit/a177743a7def37dd3fabb026241d0e0ea9e9bac3))
+
 ## [@adobe/spacecat-shared-utils-v1.113.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.112.5...@adobe/spacecat-shared-utils-v1.113.0) (2026-04-29)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.113.0",
+  "version": "1.115.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "exports": {

package/src/index.js

@@ -109,6 +109,7 @@ export { detectAEMVersion, DELIVERY_TYPES, AUTHORING_TYPES } from './aem.js';
 export { determineAEMCSPageId, getPageEditUrl } from './aem-content-api-utils.js';
 
 export * as llmoConfig from './llmo-config.js';
+export { LlmoConfigValidationError } from './llmo-config.js';
 export * as llmoStrategy from './llmo-strategy.js';
 export * as schemas from './schemas.js';
 

package/src/llmo-config.js

@@ -18,6 +18,31 @@ import { llmoConfig } from './schemas.js';
  * @import { LLMOConfig } from "./schemas.js"
  */
 
+/**
+ * Thrown by `writeConfig` when the supplied LLMO configuration does not match
+ * the published Zod schema. Exposes the offending site and the Zod issue list
+ * so callers and log readers can identify the failing fields without
+ * re-parsing the error.
+ */
+export class LlmoConfigValidationError extends Error {
+  constructor(siteId, zodError) {
+    // Use issue `code` rather than `message` in the summary: Zod's default
+    // messages can echo received values, which may include user-supplied
+    // content (brand names, competitor URLs) on the api-service write path.
+    // The full message and value remain on `this.issues` for trusted callers.
+    const summary = zodError.issues
+      .map((i) => `${i.path.join('.')}: ${i.code}`)
+      .join('; ');
+    super(
+      `LLMO config for site ${siteId} failed schema validation: ${summary}`,
+      { cause: zodError },
+    );
+    this.name = 'LlmoConfigValidationError';
+    this.siteId = siteId;
+    this.issues = zodError.issues;
+  }
+}
+
 /**
  * @param {string} siteId The ID of the site to get the config directory for.
  * @returns {string} The configuration directory path for the given site ID.
@@ -62,6 +87,10 @@ export function defaultConfig() {
  * Reads the LLMO configuration for a given site.
  * Returns an empty configuration if the configuration does not exist.
  *
+ * If the persisted config exists but fails schema validation, throws
+ * `LlmoConfigValidationError` so callers have a uniform error contract
+ * across read and write paths.
+ *
  * @param {string} sideId The ID of the site.
  * @param {S3Client} s3Client The S3 client to use for reading the configuration.
  * @param {object} [options]
@@ -70,6 +99,7 @@ export function defaultConfig() {
  * @param {string} [options.s3Bucket] Optional S3 bucket name.
  * @returns {Promise<{config: LLMOConfig, exists: boolean, version?: string}>} The configuration,
  *        a flag indicating if it existed, and the version ID if it exists.
+ * @throws {LlmoConfigValidationError} If the persisted config fails schema validation.
  * @throws {Error} If reading the configuration fails for reasons other than it not existing.
  */
 export async function readConfig(sideId, s3Client, options) {
@@ -97,20 +127,35 @@ export async function readConfig(sideId, s3Client, options) {
     throw new Error('LLMO config body is empty');
   }
   const text = await body.transformToString();
-  const config = llmoConfig.parse(JSON.parse(text));
-  return { config, exists: true, version: res.VersionId || undefined };
+  const result = llmoConfig.safeParse(JSON.parse(text));
+  if (!result.success) {
+    throw new LlmoConfigValidationError(sideId, result.error);
+  }
+  return { config: result.data, exists: true, version: res.VersionId || undefined };
 }
 
 /**
  * Writes the LLMO configuration for a given site.
+ *
+ * Validates `config` against the published Zod schema before issuing the S3
+ * `PutObject`. If validation fails, throws `LlmoConfigValidationError` and
+ * does not call S3, so invalid configs cannot reach the bucket through this
+ * function.
+ *
  * @param {string} siteId The ID of the site.
  * @param {LLMOConfig} config The configuration object to write.
  * @param {S3Client} s3Client The S3 client to use for reading the configuration.
  * @param {object} [options]
  * @param {string} [options.s3Bucket] Optional S3 bucket name.
  * @returns {Promise<{ version: string }>} The version of the configuration written.
+ * @throws {LlmoConfigValidationError} If `config` does not match the LLMO schema.
  */
 export async function writeConfig(siteId, config, s3Client, options) {
+  const result = llmoConfig.safeParse(config);
+  if (!result.success) {
+    throw new LlmoConfigValidationError(siteId, result.error);
+  }
+
   const s3Bucket = options?.s3Bucket || process.env.S3_BUCKET_NAME;
 
   const putObjectCommand = new PutObjectCommand({

package/src/strategy-schema.js

@@ -38,6 +38,10 @@ const strategyGoalType = z.union([
   z.string(), // Catchall for future goal types
 ]);
 
+// Discriminator between Atomic (experiment-driven) and Evolving (iterative) strategies.
+// Existing pre-GA strategies have no `type` field and default to 'evolving' for backward compat.
+const strategyType = z.enum(['atomic', 'evolving']);
+
 /**
  * Library opportunity - user-created reusable opportunity template
  */
@@ -76,6 +80,7 @@ const strategyPromptSelection = z.object({
  */
 const strategy = z.object({
   id: nonEmptyString,
+  type: strategyType.default('evolving'),
   name: nonEmptyString,
   status: workflowStatus,
   url: z.union([z.string(), z.array(z.string())]),
@@ -90,6 +95,7 @@ const strategy = z.object({
   createdBy: z.string().optional(), // Email of strategy creator/owner
   completedAt: z.string().optional(), // ISO 8601 date string
   goalType: strategyGoalType.optional(),
+  experimentId: z.uuid().nullable().optional(),
 });
 
 /**
@@ -138,4 +144,37 @@ export const strategyWorkspaceData = z.object({
       }
     });
   });
+
+  // Validate type-based invariants (Atomic vs Evolving)
+  strategies.forEach((strat, strategyIndex) => {
+    // Atomic must have a non-null experimentId
+    if (strat.type === 'atomic' && (strat.experimentId === undefined || strat.experimentId === null)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['strategies', strategyIndex, 'experimentId'],
+        message: 'Atomic strategies require a non-null experimentId',
+      });
+    }
+
+    // Atomic must not carry selectedPrompts (those come from GeoExperiment)
+    if (strat.type === 'atomic' && Array.isArray(strat.selectedPrompts) && strat.selectedPrompts.length > 0) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['strategies', strategyIndex, 'selectedPrompts'],
+        message: 'Atomic strategies must not carry selectedPrompts (use GeoExperiment.promptsLocation)',
+      });
+    }
+
+    // Evolving: schema is intentionally permissive on `selectedPrompts`. Today's
+    // CreateStrategyDialog initializes selectedPrompts as `[]` for newly-created
+    // Evolving strategies (no prompt-selection UI yet). Enforcing "must be
+    // non-empty" at the schema would reject those in-flight reads + writes.
+    //
+    // The "newly-created Evolving strategies must include selectedPrompts" rule
+    // is deferred to the milestone where Evolving promotes out of co-innovation
+    // mode — at that point the schema tightens, the API layer (saveStrategy)
+    // adds the creation-time check, and the prompt-selection screen ships.
+    // All three land together. Until then, selectedPrompts on Evolving is
+    // structurally validated only.
+  });
 });