@adobe/spacecat-shared-utils 1.50.7 → 1.51.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-utils-v1.51.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.50.8...@adobe/spacecat-shared-utils-v1.51.0) (2025-09-25)
+
+
+### Features
+
+* schema + file read/write for llmo config ([#981](https://github.com/adobe/spacecat-shared/issues/981)) ([93b0aae](https://github.com/adobe/spacecat-shared/commit/93b0aae0daeb1a81c6914d21b30f39b448784599))
+
+# [@adobe/spacecat-shared-utils-v1.50.8](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.50.7...@adobe/spacecat-shared-utils-v1.50.8) (2025-09-20)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#969](https://github.com/adobe/spacecat-shared/issues/969)) ([d722c62](https://github.com/adobe/spacecat-shared/commit/d722c623193fdbf292d96d71236cb4396db7ce3b))
+
 # [@adobe/spacecat-shared-utils-v1.50.7](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-utils-v1.50.6...@adobe/spacecat-shared-utils-v1.50.7) (2025-09-18)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-utils",
-  "version": "1.50.7",
+  "version": "1.51.0",
   "description": "Shared modules of the Spacecat Services - utils",
   "type": "module",
   "engines": {
@@ -48,12 +48,13 @@
     "@adobe/fetch": "4.2.3",
     "@adobe/spacecat-shared-data-access": "2.45.0",
     "@adobe/spacecat-shared-ims-client": "1.8.3",
-    "@aws-sdk/client-s3": "3.888.0",
-    "@aws-sdk/client-secrets-manager": "3.888.0",
-    "@aws-sdk/client-sqs": "3.888.0",
+    "@aws-sdk/client-s3": "3.893.0",
+    "@aws-sdk/client-secrets-manager": "3.893.0",
+    "@aws-sdk/client-sqs": "3.893.0",
     "@json2csv/plainjs": "7.0.6",
     "aws-xray-sdk": "3.10.3",
     "date-fns": "4.1.0",
-    "validator": "^13.15.15"
+    "validator": "^13.15.15",
+    "zod": "^4.1.11"
   }
 }

package/src/index.js

@@ -94,3 +94,6 @@ export {
 export { detectAEMVersion, DELIVERY_TYPES } from './aem.js';
 
 export { determineAEMCSPageId, getPageEditUrl } from './aem-content-api-utils.js';
+
+export * as llmoConfig from './llmo-config.js';
+export * as schemas from './schemas.js';

package/src/llmo-config.js

@@ -0,0 +1,119 @@
+/*
+ * 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 { GetObjectCommand, PutObjectCommand } from '@aws-sdk/client-s3';
+import { llmoConfig } from './schemas.js';
+
+/**
+ * @import { S3Client } from "@aws-sdk/client-s3"
+ * @import { LLMOConfig } from "./schemas.js"
+ */
+
+/**
+ * @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.
+ */
+export function lmmoConfigDir(siteId) {
+  return `config/llmo/${siteId}`;
+}
+
+/**
+ * @param {string} siteId The ID of the site to get the latest config file path for.
+ * @returns {string} The latest configuration file path for the given site ID.
+ */
+export function llmoConfigPath(siteId) {
+  return `${lmmoConfigDir(siteId)}/lmmo-config.json`;
+}
+
+/**
+ * Returns the default LLMO configuration.
+ * @returns {LLMOConfig} The default configuration object.
+ */
+export function defaultConfig() {
+  return {
+    entities: {},
+    brands: {
+      aliases: [],
+    },
+    competitors: {
+      competitors: [],
+    },
+  };
+}
+
+/**
+ * Reads the LLMO configuration for a given site.
+ * Returns an empty configuration if the configuration does not exist.
+ *
+ * @param {string} sideId The ID of the site.
+ * @param {S3Client} s3Client The S3 client to use for reading the configuration.
+ * @param {object} [options]
+ * @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.
+ * @throws {Error} If reading the configuration fails for reasons other than it not existing.
+ */
+export async function readConfig(sideId, s3Client, options) {
+  const version = options?.version;
+  const s3Bucket = options?.s3Bucket || process.env.S3_BUCKET_NAME;
+
+  const getObjectCommand = new GetObjectCommand({
+    Bucket: s3Bucket,
+    Key: llmoConfigPath(sideId),
+    VersionId: version,
+  });
+  let res;
+  try {
+    res = await s3Client.send(getObjectCommand);
+  } catch (e) {
+    if (e.name === 'NoSuchKey' || e.name === 'NotFound') {
+      // Config does not exist yet. Return empty config.
+      return { config: defaultConfig(), exists: false };
+    }
+    throw e;
+  }
+
+  const body = res.Body;
+  if (!body) {
+    throw new Error('LLMO config body is empty');
+  }
+  const text = await body.transformToString();
+  const config = llmoConfig.parse(JSON.parse(text));
+  return { config, exists: true };
+}
+
+/**
+ * Writes the LLMO configuration for a given site.
+ * @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.
+ */
+export async function writeConfig(siteId, config, s3Client, options) {
+  const s3Bucket = options?.s3Bucket || process.env.S3_BUCKET_NAME;
+
+  const putObjectCommand = new PutObjectCommand({
+    Bucket: s3Bucket,
+    Key: llmoConfigPath(siteId),
+    Body: JSON.stringify(config, null, 2),
+    ContentType: 'application/json',
+  });
+  const res = await s3Client.send(putObjectCommand);
+  if (!res.VersionId) {
+    throw new Error('Failed to get version ID after writing LLMO config');
+  }
+  return { version: res.VersionId };
+}

package/src/schemas.js

@@ -0,0 +1,109 @@
+/*
+ * 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.
+ */
+
+/* eslint-disable no-use-before-define */
+
+import * as z from 'zod';
+
+// ===== SCHEMA DEFINITIONS ====================================================
+// Schemas defined here must be forward- and backward-compatible when making changes.
+// This means:
+// - Always wrap arrays in an object, so that extra properties can be added later.
+// - When using unions, always include a catchall case to cover unknown future cases.
+// - Always allow extra properties in objects, so that future config versions don't break parsing.
+//   (this is the default. Do not add `.strict()`!)
+// - it is ok to add new optional properties to objects, but not to remove existing ones.
+// - enums (z.enum([...])) are not forward-compatible.
+//   Use z.string() or `z.union([..., z.string()])` instead.
+// - never rename properties, only add new ones.
+// - never broaden or narrow types.
+//   E.g., don't change `z.string()` to `z.union([z.string(), z.number()])` or vice versa.
+//   If you anticipate that need, use the union from the start.
+// ============================================================================
+
+/**
+ * @typedef {z.output<llmoConfig>} LLMOConfig
+ */
+
+const nonEmptyString = z.string().min(1);
+
+const entity = z.union([
+  z.object({ type: z.literal('category'), name: nonEmptyString }),
+  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({
+    aliases: z.array(
+      z.object({
+        aliases: z.array(nonEmptyString),
+        category: z.uuid(),
+        region: z.union([region, z.array(region)]),
+        topic: z.uuid(),
+      }),
+    ),
+  }),
+  competitors: z.object({
+    competitors: z.array(
+      z.object({
+        category: z.uuid(),
+        region: z.union([region, z.array(region)]),
+        name: nonEmptyString,
+        aliases: z.array(nonEmptyString),
+        urls: z.array(z.url().optional()),
+      }),
+    ),
+  }),
+}).superRefine((value, ctx) => {
+  const { entities, brands, competitors } = value;
+
+  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');
+  });
+
+  competitors.competitors.forEach((competitor, index) => {
+    ensureEntityType(entities, ctx, competitor.category, 'category', ['competitors', 'competitors', index, 'category'], 'category');
+  });
+});
+
+/**
+   * @param {LLMOConfig['entities']} entities
+   * @param {z.RefinementCtx} ctx
+   * @param {string} id
+   * @param {string} expectedType
+   * @param {Array<number | string>} path
+   * @param {string} refLabel
+   */
+function ensureEntityType(entities, ctx, id, expectedType, path, refLabel) {
+  const entityValue = entities[id];
+  if (!entityValue) {
+    ctx.addIssue({
+      code: 'custom',
+      path,
+      message: `Unknown ${refLabel} entity: ${id}`,
+    });
+    return;
+  }
+
+  if (entityValue.type !== expectedType) {
+    ctx.addIssue({
+      code: 'custom',
+      path,
+      message: `Entity ${id} referenced as ${refLabel} must have type "${expectedType}" but was "${entityValue.type}"`,
+    });
+  }
+}