@adobe/spacecat-shared-utils 1.91.0 → 1.92.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-utils-v1.92.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.91.0...@adobe/spacecat-shared-utils-v1.92.0) (2026-02-10)
+
+
+### Features
+
+* schema for oppty workspace data ([#1307](https://github.com/adobe/spacecat-shared/issues/1307)) ([49decad](https://github.com/adobe/spacecat-shared/commit/49decada5a0e598628563c8856b77715de549fce))
+
 # [@adobe/spacecat-shared-utils-v1.91.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.90.3...@adobe/spacecat-shared-utils-v1.91.0) (2026-02-08)
 
 

package/package.json

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

package/src/llmo-strategy.js

@@ -11,9 +11,13 @@
  */
 
 import { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
+import { strategyWorkspaceData } from './strategy-schema.js';
+
+export { strategyWorkspaceData };
 
 /**
  * @import { S3Client } from "@aws-sdk/client-s3"
+ * @import { StrategyWorkspaceData } from "./strategy-schema.js"
  */
 
 /**
@@ -34,8 +38,8 @@ export function strategyPath(siteId) {
  * @param {string} [options.version] Optional version ID of the strategy to read.
  *        Defaults to the latest version.
  * @param {string} [options.s3Bucket] Optional S3 bucket name.
- * @returns {Promise<{data: object | null, exists: boolean, version?: string}>} The strategy data,
- *        a flag indicating if it existed, and the version ID if it exists.
+ * @returns {Promise<{data: StrategyWorkspaceData | null, exists: boolean, version?: string}>}
+ *        The strategy data, a flag indicating if it existed, and the version ID if it exists.
  * @throws {Error} If reading the strategy fails for reasons other than it not existing.
  */
 export async function readStrategy(siteId, s3Client, options) {
@@ -64,14 +68,14 @@ export async function readStrategy(siteId, s3Client, options) {
     throw new Error('Strategy body is empty');
   }
   const text = await body.transformToString();
-  const data = JSON.parse(text);
+  const data = strategyWorkspaceData.parse(JSON.parse(text));
   return { data, exists: true, version: res.VersionId || undefined };
 }
 
 /**
  * Writes the strategy JSON for a given site.
  * @param {string} siteId The ID of the site.
- * @param {object} data The data object to write (any valid JSON).
+ * @param {StrategyWorkspaceData} data The strategy data object to write.
  * @param {S3Client} s3Client The S3 client to use for writing the strategy.
  * @param {object} [options]
  * @param {string} [options.s3Bucket] Optional S3 bucket name.

package/src/strategy-schema.js

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import * as z from 'zod';
+
+// ===== SCHEMA DEFINITIONS ====================================================
+// Schemas defined here must be forward- and backward-compatible when making changes.
+// See llmoConfig schema for detailed guidelines.
+// ============================================================================
+
+/**
+ * @typedef {z.output<typeof strategyWorkspaceData>} StrategyWorkspaceData
+ */
+
+const nonEmptyString = z.string().min(1);
+
+// Shared status union for forward compatibility
+const workflowStatus = z.union([
+  z.literal('new'),
+  z.literal('planning'),
+  z.literal('in_progress'),
+  z.literal('completed'),
+  z.literal('on_hold'),
+  z.string(), // Catchall for future statuses
+]);
+
+const strategyGoalType = z.union([
+  z.literal('visibility-score'),
+  z.string(), // Catchall for future goal types
+]);
+
+/**
+ * Library opportunity - user-created reusable opportunity template
+ */
+const opportunity = z.object({
+  id: nonEmptyString,
+  name: nonEmptyString,
+  description: z.string(),
+  category: nonEmptyString,
+});
+
+/**
+ * Reference to an opportunity within a strategy
+ * Two types:
+ * 1. Library opportunity: opportunityId references Opportunity.id, no link field
+ * 2. System opportunity: has link field, opportunityId is system ID
+ */
+const strategyOpportunity = z.object({
+  opportunityId: nonEmptyString,
+  name: z.string().optional(), // For system opportunities (name stored directly)
+  link: z.string().optional(), // URL path to opportunity page (system-generated)
+  status: workflowStatus,
+  assignee: z.string(),
+  completedAt: z.string().optional(), // ISO 8601 date string
+});
+
+/**
+ * Strategy containing references to opportunities
+ */
+const strategy = z.object({
+  id: nonEmptyString,
+  name: nonEmptyString,
+  status: workflowStatus,
+  url: z.string(),
+  description: z.string(),
+  topic: z.string(),
+  platform: nonEmptyString,
+  opportunities: z.array(strategyOpportunity),
+  createdAt: z.string(), // ISO 8601 date string
+  completedAt: z.string().optional(), // ISO 8601 date string
+  goalType: strategyGoalType.optional(),
+});
+
+/**
+ * Root schema for strategy workspace data
+ */
+export const strategyWorkspaceData = z.object({
+  opportunities: z.array(opportunity),
+  strategies: z.array(strategy),
+}).superRefine((value, ctx) => {
+  const { opportunities, strategies } = value;
+
+  // Build a set of library opportunity IDs for reference validation
+  const libraryOpportunityIds = new Set(opportunities.map((opp) => opp.id));
+
+  // Validate that library opportunity references exist
+  strategies.forEach((strat, strategyIndex) => {
+    strat.opportunities.forEach((stratOpp, oppIndex) => {
+      // Only validate library opportunities (those without a link)
+      if (!stratOpp.link && !libraryOpportunityIds.has(stratOpp.opportunityId)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['strategies', strategyIndex, 'opportunities', oppIndex, 'opportunityId'],
+          message: `Library opportunity ${stratOpp.opportunityId} does not exist`,
+        });
+      }
+    });
+  });
+
+  // Validate completedAt consistency with status
+  strategies.forEach((strat, strategyIndex) => {
+    if (strat.status === 'completed' && !strat.completedAt) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['strategies', strategyIndex, 'completedAt'],
+        message: 'completedAt is required when status is completed',
+      });
+    }
+
+    strat.opportunities.forEach((stratOpp, oppIndex) => {
+      if (stratOpp.status === 'completed' && !stratOpp.completedAt) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['strategies', strategyIndex, 'opportunities', oppIndex, 'completedAt'],
+          message: 'completedAt is required when status is completed',
+        });
+      }
+    });
+  });
+});