feat(utils): add semantic lookup source/entity type registries (LLMO-7445)

Author: Tanase Butcaru

packages/spacecat-shared-utils/src/constants.d.ts

@@ -11,3 +11,24 @@
  */
 
 export { OPPORTUNITY_TYPES, DEFAULT_CPC_VALUE } from './index.js';
+
+export const OPPORTUNITY_SEMANTIC_SOURCE_TYPES: Readonly<{
+  TOPIC: 'topic';
+}>;
+
+export const OPPORTUNITY_SEMANTIC_ENTITY_TYPES: Readonly<{
+  CITED_ANALYSIS: 'cited-analysis';
+  REDDIT_ANALYSIS: 'reddit-analysis';
+  YOUTUBE_ANALYSIS: 'youtube-analysis';
+}>;
+
+export const SUGGESTION_SEMANTIC_SOURCE_TYPES: Readonly<{
+  TOPIC: 'topic';
+  TITLE: 'title';
+}>;
+
+export const SUGGESTION_SEMANTIC_ENTITY_TYPES: Readonly<{
+  CITED_ANALYSIS: 'cited-analysis';
+  REDDIT_ANALYSIS: 'reddit-analysis';
+  YOUTUBE_ANALYSIS: 'youtube-analysis';
+}>;

packages/spacecat-shared-utils/src/constants.js

@@ -77,3 +77,40 @@ export const OPPORTUNITY_TYPES = /** @type {const} */ ({
 });
 
 export const DEFAULT_CPC_VALUE = 1.5;
+
+/**
+ * Kinds of source text in `opportunity_semantic_embedding.source_type`. The semantic lookup writer
+ * and reader reject any other value; add a kind here before indexing or searching it.
+ */
+export const OPPORTUNITY_SEMANTIC_SOURCE_TYPES = Object.freeze({
+  TOPIC: 'topic',
+});
+
+/**
+ * Opportunity types allowed in `opportunity_semantic_embedding.entity_type`. The writer and reader
+ * reject any other value; add a type here before indexing or filtering by it.
+ */
+export const OPPORTUNITY_SEMANTIC_ENTITY_TYPES = Object.freeze({
+  CITED_ANALYSIS: OPPORTUNITY_TYPES.CITED_ANALYSIS,
+  REDDIT_ANALYSIS: OPPORTUNITY_TYPES.REDDIT_ANALYSIS,
+  YOUTUBE_ANALYSIS: OPPORTUNITY_TYPES.YOUTUBE_ANALYSIS,
+});
+
+/**
+ * Kinds of source text in `suggestion_semantic_embedding.source_type`: the suggestion's derived
+ * topics and its title. Same enforcement as `OPPORTUNITY_SEMANTIC_SOURCE_TYPES`.
+ */
+export const SUGGESTION_SEMANTIC_SOURCE_TYPES = Object.freeze({
+  TOPIC: 'topic',
+  TITLE: 'title',
+});
+
+/**
+ * Parent opportunity types allowed in `suggestion_semantic_embedding.entity_type`. Same
+ * enforcement as `OPPORTUNITY_SEMANTIC_ENTITY_TYPES`.
+ */
+export const SUGGESTION_SEMANTIC_ENTITY_TYPES = Object.freeze({
+  CITED_ANALYSIS: OPPORTUNITY_TYPES.CITED_ANALYSIS,
+  REDDIT_ANALYSIS: OPPORTUNITY_TYPES.REDDIT_ANALYSIS,
+  YOUTUBE_ANALYSIS: OPPORTUNITY_TYPES.YOUTUBE_ANALYSIS,
+});

packages/spacecat-shared-utils/src/index.d.ts

@@ -17,6 +17,13 @@ export { AUTHORING_TYPES, DELIVERY_TYPES } from './aem.js';
 
 export { OPPORTUNITY_TYPES } from './constants.js';
 
+export {
+  OPPORTUNITY_SEMANTIC_SOURCE_TYPES,
+  OPPORTUNITY_SEMANTIC_ENTITY_TYPES,
+  SUGGESTION_SEMANTIC_SOURCE_TYPES,
+  SUGGESTION_SEMANTIC_ENTITY_TYPES,
+} from './constants.js';
+
 export const DEFAULT_CPC_VALUE: number;
 
 /** UTILITY FUNCTIONS */

packages/spacecat-shared-utils/src/index.js

@@ -92,7 +92,14 @@ export { getStoredMetrics, storeMetrics, calculateCPCValue } from './metrics-sto
 
 export { s3Wrapper, getObjectFromKey } from './s3.js';
 
-export { OPPORTUNITY_TYPES, DEFAULT_CPC_VALUE } from './constants.js';
+export {
+  OPPORTUNITY_TYPES,
+  DEFAULT_CPC_VALUE,
+  OPPORTUNITY_SEMANTIC_SOURCE_TYPES,
+  OPPORTUNITY_SEMANTIC_ENTITY_TYPES,
+  SUGGESTION_SEMANTIC_SOURCE_TYPES,
+  SUGGESTION_SEMANTIC_ENTITY_TYPES,
+} from './constants.js';
 
 export { fetch, resetFetchContext, clearFetchCache } from './adobe-fetch.js';
 export { tracingFetch, SPACECAT_USER_AGENT } from './tracing-fetch.js';

packages/spacecat-shared-utils/test/constants.test.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2026 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 { expect } from 'chai';
+import {
+  OPPORTUNITY_SEMANTIC_SOURCE_TYPES,
+  OPPORTUNITY_SEMANTIC_ENTITY_TYPES,
+  SUGGESTION_SEMANTIC_SOURCE_TYPES,
+  SUGGESTION_SEMANTIC_ENTITY_TYPES,
+} from '../src/constants.js';
+
+describe('semantic lookup type registries', () => {
+  it('lists the opportunity source and entity types', () => {
+    expect(OPPORTUNITY_SEMANTIC_SOURCE_TYPES).to.deep.equal({ TOPIC: 'topic' });
+    expect(OPPORTUNITY_SEMANTIC_ENTITY_TYPES).to.deep.equal({
+      CITED_ANALYSIS: 'cited-analysis',
+      REDDIT_ANALYSIS: 'reddit-analysis',
+      YOUTUBE_ANALYSIS: 'youtube-analysis',
+    });
+  });
+
+  it('lists the suggestion source and entity types', () => {
+    expect(SUGGESTION_SEMANTIC_SOURCE_TYPES).to.deep.equal({ TOPIC: 'topic', TITLE: 'title' });
+    expect(SUGGESTION_SEMANTIC_ENTITY_TYPES).to.deep.equal({
+      CITED_ANALYSIS: 'cited-analysis',
+      REDDIT_ANALYSIS: 'reddit-analysis',
+      YOUTUBE_ANALYSIS: 'youtube-analysis',
+    });
+  });
+
+  it('freezes every registry', () => {
+    [
+      OPPORTUNITY_SEMANTIC_SOURCE_TYPES,
+      OPPORTUNITY_SEMANTIC_ENTITY_TYPES,
+      SUGGESTION_SEMANTIC_SOURCE_TYPES,
+      SUGGESTION_SEMANTIC_ENTITY_TYPES,
+    ].forEach((registry) => expect(Object.isFrozen(registry)).to.equal(true));
+  });
+});

packages/spacecat-shared-utils/test/index.test.js

@@ -110,6 +110,8 @@ describe('Index Exports', () => {
     'logWrapper',
     'OPPORTUNITY_DEPENDENCY_MAP',
     'OPPORTUNITY_GRANT_CONFIG',
+    'OPPORTUNITY_SEMANTIC_ENTITY_TYPES',
+    'OPPORTUNITY_SEMANTIC_SOURCE_TYPES',
     'OPPORTUNITY_TITLES',
     'OPPORTUNITY_TYPES',
     'prependSchema',
@@ -130,6 +132,8 @@ describe('Index Exports', () => {
     'stripTrailingDot',
     'stripTrailingSlash',
     'stripWWW',
+    'SUGGESTION_SEMANTIC_ENTITY_TYPES',
+    'SUGGESTION_SEMANTIC_SOURCE_TYPES',
     'TOKEN_GRANT_CONFIG',
     'toBoolean',
     'filterBySiteScope',

packages/spacecat-shared-utils/test/subpaths.test.js

@@ -57,6 +57,8 @@ const EXPECTED_SCHEMAS_EXPORTS = [
 
 const EXPECTED_CONSTANTS_EXPORTS = [
   'DEFAULT_CPC_VALUE', 'OPPORTUNITY_TYPES',
+  'OPPORTUNITY_SEMANTIC_SOURCE_TYPES', 'OPPORTUNITY_SEMANTIC_ENTITY_TYPES',
+  'SUGGESTION_SEMANTIC_SOURCE_TYPES', 'SUGGESTION_SEMANTIC_ENTITY_TYPES',
 ];
 
 const pkgDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');