@adobe/spacecat-shared-utils 1.51.1 → 1.53.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-utils-v1.53.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.52.0...@adobe/spacecat-shared-utils-v1.53.0) (2025-10-02)
+
+
+### Features
+
+* Add regions to categories and related validation on dependent entities ([#996](https://github.com/adobe/spacecat-shared/issues/996)) ([60c52e2](https://github.com/adobe/spacecat-shared/commit/60c52e2d9c7e79a67132ae2b26e40e617e8af358))
+
+# [@adobe/spacecat-shared-utils-v1.52.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.51.1...@adobe/spacecat-shared-utils-v1.52.0) (2025-09-29)
+
+
+### Features
+
+* llmo config types and version ([#990](https://github.com/adobe/spacecat-shared/issues/990)) ([2dfe331](https://github.com/adobe/spacecat-shared/commit/2dfe33156754f044b6e9ff18d32e13baabaa47f1))
+
 # [@adobe/spacecat-shared-utils-v1.51.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.51.0...@adobe/spacecat-shared-utils-v1.51.1) (2025-09-25)
 
 

package/package.json

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

package/src/index.d.ts

@@ -262,3 +262,6 @@ export function tracingFetch(url: string | Request, options?: RequestOptions): P
 export const SPACECAT_USER_AGENT: string;
 
 export function retrievePageAuthentication(site: object, context: object): Promise<string>;
+
+export * as llmoConfig from './llmo-config.js';
+export * as schemas from './schemas.js';

package/src/llmo-config.js

@@ -60,8 +60,8 @@ export function defaultConfig() {
  * @param {string} [options.version] Optional version ID of the configuration to read.
  *        Defaults to the latest version.
  * @param {string} [options.s3Bucket] Optional S3 bucket name.
- * @returns {Promise<{config: LLMOConfig, exists: boolean}>} The configuration object and
- *        a flag indicating if it existed.
+ * @returns {Promise<{config: LLMOConfig, exists: boolean, version?: string}>} The configuration,
+ *        a flag indicating if it existed, and the version ID if it exists.
  * @throws {Error} If reading the configuration fails for reasons other than it not existing.
  */
 export async function readConfig(sideId, s3Client, options) {
@@ -79,7 +79,7 @@ export async function readConfig(sideId, s3Client, options) {
   } catch (e) {
     if (e.name === 'NoSuchKey' || e.name === 'NotFound') {
       // Config does not exist yet. Return empty config.
-      return { config: defaultConfig(), exists: false };
+      return { config: defaultConfig(), exists: false, version: undefined };
     }
     throw e;
   }
@@ -90,7 +90,7 @@ export async function readConfig(sideId, s3Client, options) {
   }
   const text = await body.transformToString();
   const config = llmoConfig.parse(JSON.parse(text));
-  return { config, exists: true };
+  return { config, exists: true, version: res.VersionId || undefined };
 }
 
 /**

package/src/schemas.js

@@ -36,14 +36,14 @@ import * as z from 'zod';
 
 const nonEmptyString = z.string().min(1);
 
+const region = z.string().length(2).regex(/^[a-z][a-z]$/i);
+
 const entity = z.union([
-  z.object({ type: z.literal('category'), name: nonEmptyString }),
+  z.object({ type: z.literal('category'), name: nonEmptyString, region: z.union([region, z.array(region)]).optional() }),
   z.object({ type: z.literal('topic'), name: nonEmptyString }),
   z.object({ type: nonEmptyString }),
 ]);
 
-const region = z.string().length(2).regex(/^[a-z][a-z]$/i);
-
 export const llmoConfig = z.object({
   entities: z.record(z.uuid(), entity),
   brands: z.object({
@@ -73,10 +73,12 @@ export const llmoConfig = z.object({
   brands.aliases.forEach((alias, index) => {
     ensureEntityType(entities, ctx, alias.category, 'category', ['brands', 'aliases', index, 'category'], 'category');
     ensureEntityType(entities, ctx, alias.topic, 'topic', ['brands', 'aliases', index, 'topic'], 'topic');
+    ensureRegionCompatibility(entities, ctx, alias.category, alias.region, ['brands', 'aliases', index, 'region'], 'brand alias');
   });
 
   competitors.competitors.forEach((competitor, index) => {
     ensureEntityType(entities, ctx, competitor.category, 'category', ['competitors', 'competitors', index, 'category'], 'category');
+    ensureRegionCompatibility(entities, ctx, competitor.category, competitor.region, ['competitors', 'competitors', index, 'region'], 'competitor');
   });
 });
 
@@ -107,3 +109,47 @@ function ensureEntityType(entities, ctx, id, expectedType, path, refLabel) {
     });
   }
 }
+
+/**
+ * @param {LLMOConfig['entities']} entities
+ * @param {z.RefinementCtx} ctx
+ * @param {string} categoryId
+ * @param {string | string[]} itemRegion
+ * @param {Array<number | string>} path
+ * @param {string} itemLabel
+ */
+function ensureRegionCompatibility(entities, ctx, categoryId, itemRegion, path, itemLabel) {
+  const categoryEntity = entities[categoryId];
+  if (!categoryEntity) {
+    // Category validation is handled by ensureEntityType
+    return;
+  }
+
+  const categoryRegions = categoryEntity.region;
+
+  // If category has no regions defined, item should not have regions
+  if (!categoryRegions) {
+    ctx.addIssue({
+      code: 'custom',
+      path,
+      message: `${itemLabel} cannot have regions when the referenced category has no regions defined`,
+    });
+    return;
+  }
+
+  // Normalize regions to arrays for comparison
+  const categoryRegionArray = Array.isArray(categoryRegions) ? categoryRegions : [categoryRegions];
+  const itemRegionArray = Array.isArray(itemRegion) ? itemRegion : [itemRegion];
+
+  // Check if all item regions are contained in category regions
+  const invalidRegions = itemRegionArray.filter(
+    (regionItem) => !categoryRegionArray.includes(regionItem),
+  );
+  if (invalidRegions.length > 0) {
+    ctx.addIssue({
+      code: 'custom',
+      path,
+      message: `${itemLabel} regions [${invalidRegions.join(', ')}] are not allowed. Category only supports regions: [${categoryRegionArray.join(', ')}]`,
+    });
+  }
+}