@adobe/spacecat-shared-data-access 2.102.0 → 2.103.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-data-access-v2.103.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.102.0...@adobe/spacecat-shared-data-access-v2.103.0) (2026-02-04)
+
+
+### Features
+
+* add brand sentiment guidelines ([#1297](https://github.com/adobe/spacecat-shared/issues/1297)) ([93f0a1d](https://github.com/adobe/spacecat-shared/commit/93f0a1dada56c1a3b6c40cff32a4b7be186e82e6))
+
 # [@adobe/spacecat-shared-data-access-v2.102.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.101.0...@adobe/spacecat-shared-data-access-v2.102.0) (2026-02-04)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.102.0",
+  "version": "2.103.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/entity.registry.js

@@ -42,6 +42,8 @@ import ReportCollection from '../report/report.collection.js';
 import TrialUserCollection from '../trial-user/trial-user.collection.js';
 import TrialUserActivityCollection from '../trial-user-activity/trial-user-activity.collection.js';
 import PageCitabilityCollection from '../page-citability/page-citability.collection.js';
+import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guideline.collection.js';
+import SentimentTopicCollection from '../sentiment-topic/sentiment-topic.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -71,6 +73,8 @@ import ReportSchema from '../report/report.schema.js';
 import TrialUserSchema from '../trial-user/trial-user.schema.js';
 import TrialUserActivitySchema from '../trial-user-activity/trial-user-activity.schema.js';
 import PageCitabilitySchema from '../page-citability/page-citability.schema.js';
+import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline.schema.js';
+import SentimentTopicSchema from '../sentiment-topic/sentiment-topic.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -179,5 +183,7 @@ EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);
 EntityRegistry.registerEntity(PageCitabilitySchema, PageCitabilityCollection);
+EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollection);
+EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
 
 export default EntityRegistry;

package/src/models/index.d.ts

@@ -35,3 +35,5 @@ export type * from './suggestion';
 export type * from './report';
 export type * from './trial-user';
 export type * from './trial-user-activity';
+export type * from './sentiment-guideline';
+export type * from './sentiment-topic';

package/src/models/index.js

@@ -40,3 +40,5 @@ export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';
 export * from './page-citability/index.js';
+export * from './sentiment-guideline/index.js';
+export * from './sentiment-topic/index.js';

package/src/models/sentiment-guideline/index.d.ts

@@ -0,0 +1,51 @@
+/*
+ * 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 type { BaseCollection, BaseModel, Site } from '../index';
+
+/**
+ * SentimentGuideline entity representing a guideline for sentiment analysis.
+ * Composite primary key: siteId (PK) + guidelineId (SK)
+ */
+export interface SentimentGuideline extends BaseModel {
+  getGuidelineId(): string;
+  getName(): string;
+  getInstruction(): string;
+  getAudits(): string[];
+  getEnabled(): boolean;
+  getCreatedAt(): string;
+  getCreatedBy(): string;
+  getUpdatedAt(): string;
+  getUpdatedBy(): string;
+  getSite(): Promise<Site>;
+  getSiteId(): string;
+
+  setName(name: string): SentimentGuideline;
+  setInstruction(instruction: string): SentimentGuideline;
+  setAudits(audits: string[]): SentimentGuideline;
+  setEnabled(enabled: boolean): SentimentGuideline;
+  setUpdatedBy(updatedBy: string): SentimentGuideline;
+
+  isEnabled(): boolean;
+  isAuditEnabled(auditType: string): boolean;
+  enableAudit(auditType: string): SentimentGuideline;
+  disableAudit(auditType: string): SentimentGuideline;
+}
+
+export interface SentimentGuidelineCollection extends BaseCollection<SentimentGuideline> {
+  findById(siteId: string, guidelineId: string): Promise<SentimentGuideline | null>;
+  allBySiteId(siteId: string, options?: { limit?: number; cursor?: string }): Promise<{ data: SentimentGuideline[]; cursor: string | null }>;
+  allBySiteIdEnabled(siteId: string, options?: { limit?: number; cursor?: string }): Promise<{ data: SentimentGuideline[]; cursor: string | null }>;
+  allBySiteIdAndAuditType(siteId: string, auditType: string, options?: { limit?: number; cursor?: string }): Promise<{ data: SentimentGuideline[]; cursor: string | null }>;
+  findByIds(siteId: string, guidelineIds: string[]): Promise<SentimentGuideline[]>;
+  removeForSiteId(siteId: string): Promise<void>;
+}

package/src/models/sentiment-guideline/index.js

@@ -0,0 +1,19 @@
+/*
+ * 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 SentimentGuideline from './sentiment-guideline.model.js';
+import SentimentGuidelineCollection from './sentiment-guideline.collection.js';
+
+export {
+  SentimentGuideline,
+  SentimentGuidelineCollection,
+};

package/src/models/sentiment-guideline/sentiment-guideline.collection.js

@@ -0,0 +1,174 @@
+/*
+ * 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 { hasText } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * SentimentGuidelineCollection - A collection class for managing SentimentGuideline entities.
+ * Extends BaseCollection to provide specific methods for sentiment guidelines.
+ *
+ * @class SentimentGuidelineCollection
+ * @extends BaseCollection
+ */
+class SentimentGuidelineCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SentimentGuidelineCollection';
+
+  /**
+   * Finds a sentiment guideline by its composite primary key (siteId + guidelineId).
+   *
+   * @param {string} siteId - The site ID (partition key).
+   * @param {string} guidelineId - The guideline ID (sort key).
+   * @returns {Promise<SentimentGuideline|null>} The found SentimentGuideline or null.
+   */
+  async findById(siteId, guidelineId) {
+    if (!hasText(siteId) || !hasText(guidelineId)) {
+      throw new Error('Both siteId and guidelineId are required');
+    }
+
+    return this.findByIndexKeys({ siteId, guidelineId });
+  }
+
+  /**
+   * Gets all sentiment guidelines for a site with pagination.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: SentimentGuideline[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteId(siteId, options = {}) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      { ...options, returnCursor: true },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+
+  /**
+   * Gets all enabled sentiment guidelines for a site.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: SentimentGuideline[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteIdEnabled(siteId, options = {}) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      {
+        ...options,
+        returnCursor: true,
+        where: (attr, op) => op.eq(attr.enabled, true),
+      },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+
+  /**
+   * Gets all sentiment guidelines for a site that have a specific audit type enabled.
+   * Uses FilterExpression to filter at the database level.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {string} auditType - The audit type to filter by.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: SentimentGuideline[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteIdAndAuditType(siteId, auditType, options = {}) {
+    if (!hasText(siteId) || !hasText(auditType)) {
+      throw new Error('Both siteId and auditType are required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      {
+        ...options,
+        returnCursor: true,
+        where: (attr, op) => op.contains(attr.audits, auditType),
+      },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+
+  /**
+   * Finds multiple guidelines by their IDs using batch get.
+   * Useful for resolving guidelineIds from a SentimentTopic.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {string[]} guidelineIds - Array of guideline IDs to fetch.
+   * @returns {Promise<SentimentGuideline[]>} Array of found guidelines.
+   */
+  async findByIds(siteId, guidelineIds) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    if (!Array.isArray(guidelineIds) || guidelineIds.length === 0) {
+      return [];
+    }
+
+    // Fetch all guidelines for the site and filter
+    // Note: For large datasets, consider implementing batch get
+    const result = await this.allBySiteId(siteId);
+    const allGuidelines = result.data || [];
+    const guidelineIdSet = new Set(guidelineIds);
+
+    return allGuidelines.filter((guideline) => {
+      const id = guideline.getGuidelineId?.() ?? guideline.guidelineId;
+      return guidelineIdSet.has(id);
+    });
+  }
+
+  /**
+   * Removes all sentiment guidelines for a specific site.
+   *
+   * @param {string} siteId - The site ID.
+   * @returns {Promise<void>}
+   */
+  async removeForSiteId(siteId) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allBySiteId(siteId);
+    const guidelinesToRemove = result.data || [];
+
+    if (guidelinesToRemove.length > 0) {
+      const keysToRemove = guidelinesToRemove.map((guideline) => ({
+        siteId,
+        guidelineId: guideline.getGuidelineId?.() ?? guideline.guidelineId,
+      }));
+      await this.removeByIndexKeys(keysToRemove);
+    }
+  }
+}
+
+export default SentimentGuidelineCollection;

package/src/models/sentiment-guideline/sentiment-guideline.model.js

@@ -0,0 +1,90 @@
+/*
+ * 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 BaseModel from '../base/base.model.js';
+
+/**
+ * SentimentGuideline - A class representing a sentiment analysis guideline.
+ * Guidelines define how to analyze topics (e.g., "Focus on product quality").
+ *
+ * @class SentimentGuideline
+ * @extends BaseModel
+ */
+class SentimentGuideline extends BaseModel {
+  static ENTITY_NAME = 'SentimentGuideline';
+
+  /**
+   * Checks if this guideline is currently enabled.
+   * @returns {boolean} True if the guideline is enabled.
+   */
+  isEnabled() {
+    return this.getEnabled?.() ?? this.enabled ?? true;
+  }
+
+  /**
+   * Checks if this guideline is enabled for a specific audit type.
+   * @param {string} auditType - The audit type to check.
+   * @returns {boolean} True if the audit is enabled for this guideline.
+   */
+  isAuditEnabled(auditType) {
+    const audits = this.getAudits?.() ?? this.audits ?? [];
+    return audits.includes(auditType);
+  }
+
+  /**
+   * Adds an audit type to the audits array if not already present.
+   * @param {string} auditType - The audit type to add.
+   * @returns {this} The current instance for chaining.
+   */
+  enableAudit(auditType) {
+    const audits = this.getAudits?.() ?? this.audits ?? [];
+    if (!audits.includes(auditType)) {
+      const updatedAudits = [...audits, auditType];
+      if (this.setAudits) {
+        this.setAudits(updatedAudits);
+      } else {
+        this.audits = updatedAudits;
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Removes an audit type from the audits array.
+   * @param {string} auditType - The audit type to remove.
+   * @returns {this} The current instance for chaining.
+   */
+  disableAudit(auditType) {
+    const audits = this.getAudits?.() ?? this.audits ?? [];
+    const filtered = audits.filter((a) => a !== auditType);
+    if (this.setAudits) {
+      this.setAudits(filtered);
+    } else {
+      this.audits = filtered;
+    }
+    return this;
+  }
+
+  /**
+   * Generates the composite keys for remove/update operations.
+   * Required for entities with composite primary keys.
+   * @returns {Object} - The composite keys (siteId + guidelineId).
+   */
+  generateCompositeKeys() {
+    return {
+      siteId: this.getSiteId(),
+      guidelineId: this.getGuidelineId(),
+    };
+  }
+}
+
+export default SentimentGuideline;

package/src/models/sentiment-guideline/sentiment-guideline.schema.js

@@ -0,0 +1,79 @@
+/*
+ * 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.
+ */
+
+/* c8 ignore start */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import SentimentGuideline from './sentiment-guideline.model.js';
+import SentimentGuidelineCollection from './sentiment-guideline.collection.js';
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+
+Data Access Patterns:
+1. Get all guidelines for a site: allBySiteId(siteId)
+2. Get a specific guideline: findById(siteId, guidelineId)
+3. Get enabled guidelines: allBySiteIdEnabled(siteId) - uses FilterExpression
+4. Get guidelines by audit type: allBySiteIdAndAuditType(siteId, auditType) - uses FilterExpression
+5. Get multiple guidelines by IDs: findByIds(siteId, guidelineIds)
+
+Primary Key (Composite):
+- Partition Key (PK): siteId
+- Sort Key (SK): guidelineId
+- Provides natural uniqueness for siteId + guidelineId combinations
+
+No GSI needed - all queries are site-scoped with FilterExpression
+*/
+
+const schema = new SchemaBuilder(SentimentGuideline, SentimentGuidelineCollection)
+  .withPrimaryPartitionKeys(['siteId'])
+  .withPrimarySortKeys(['guidelineId'])
+  .addReference('belongs_to', 'Site')
+  .addAttribute('guidelineId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    default: () => crypto.randomUUID(),
+  })
+  .addAttribute('name', {
+    type: 'string',
+    required: true,
+    validate: (value) => hasText(value),
+  })
+  .addAttribute('instruction', {
+    type: 'string',
+    required: true,
+    validate: (value) => hasText(value),
+  })
+  .addAttribute('audits', {
+    type: 'set',
+    items: 'string',
+    required: true,
+    default: [],
+  })
+  .addAttribute('enabled', {
+    type: 'boolean',
+    required: true,
+    default: true,
+  })
+  .addAttribute('createdBy', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    default: 'system',
+  });
+
+export default schema.build();

package/src/models/sentiment-topic/index.d.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 type { BaseCollection, BaseModel, Site } from '../index';
+
+/**
+ * SentimentTopic entity representing a topic for sentiment analysis.
+ * Composite primary key: siteId (PK) + topicId (SK)
+ */
+export interface SentimentTopic extends BaseModel {
+  getTopicId(): string;
+  getName(): string;
+  getDescription(): string | undefined;
+  getSubPrompts(): string[];
+  getEnabled(): boolean;
+  getCreatedAt(): string;
+  getCreatedBy(): string;
+  getUpdatedAt(): string;
+  getUpdatedBy(): string;
+  getSite(): Promise<Site>;
+  getSiteId(): string;
+
+  setName(name: string): SentimentTopic;
+  setDescription(description: string): SentimentTopic;
+  setSubPrompts(subPrompts: string[]): SentimentTopic;
+  setEnabled(enabled: boolean): SentimentTopic;
+  setUpdatedBy(updatedBy: string): SentimentTopic;
+
+  addSubPrompt(prompt: string): SentimentTopic;
+  removeSubPrompt(prompt: string): SentimentTopic;
+}
+
+export interface SentimentTopicCollection extends BaseCollection<SentimentTopic> {
+  findById(siteId: string, topicId: string): Promise<SentimentTopic | null>;
+  allBySiteId(siteId: string, options?: { limit?: number; cursor?: string }): Promise<{ data: SentimentTopic[]; cursor: string | null }>;
+  allBySiteIdEnabled(siteId: string, options?: { limit?: number; cursor?: string }): Promise<{ data: SentimentTopic[]; cursor: string | null }>;
+  removeForSiteId(siteId: string): Promise<void>;
+}

package/src/models/sentiment-topic/index.js

@@ -0,0 +1,19 @@
+/*
+ * 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 SentimentTopic from './sentiment-topic.model.js';
+import SentimentTopicCollection from './sentiment-topic.collection.js';
+
+export {
+  SentimentTopic,
+  SentimentTopicCollection,
+};

package/src/models/sentiment-topic/sentiment-topic.collection.js

@@ -0,0 +1,116 @@
+/*
+ * 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 { hasText } from '@adobe/spacecat-shared-utils';
+
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * SentimentTopicCollection - A collection class for managing SentimentTopic entities.
+ * Extends BaseCollection to provide specific methods for sentiment topics.
+ *
+ * @class SentimentTopicCollection
+ * @extends BaseCollection
+ */
+class SentimentTopicCollection extends BaseCollection {
+  static COLLECTION_NAME = 'SentimentTopicCollection';
+
+  /**
+   * Finds a sentiment topic by its composite primary key (siteId + topicId).
+   *
+   * @param {string} siteId - The site ID (partition key).
+   * @param {string} topicId - The topic ID (sort key).
+   * @returns {Promise<SentimentTopic|null>} The found SentimentTopic or null.
+   */
+  async findById(siteId, topicId) {
+    if (!hasText(siteId) || !hasText(topicId)) {
+      throw new Error('Both siteId and topicId are required');
+    }
+
+    return this.findByIndexKeys({ siteId, topicId });
+  }
+
+  /**
+   * Gets all sentiment topics for a site with pagination.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: SentimentTopic[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteId(siteId, options = {}) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      { ...options, returnCursor: true },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+
+  /**
+   * Gets all enabled sentiment topics for a site.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: SentimentTopic[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteIdEnabled(siteId, options = {}) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      {
+        ...options,
+        returnCursor: true,
+        where: (attr, op) => op.eq(attr.enabled, true),
+      },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+
+  /**
+   * Removes all sentiment topics for a specific site.
+   *
+   * @param {string} siteId - The site ID.
+   * @returns {Promise<void>}
+   */
+  async removeForSiteId(siteId) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allBySiteId(siteId);
+    const topicsToRemove = result.data || [];
+
+    if (topicsToRemove.length > 0) {
+      const keysToRemove = topicsToRemove.map((topic) => ({
+        siteId,
+        topicId: topic.getTopicId?.() ?? topic.topicId,
+      }));
+      await this.removeByIndexKeys(keysToRemove);
+    }
+  }
+}
+
+export default SentimentTopicCollection;

package/src/models/sentiment-topic/sentiment-topic.model.js

@@ -0,0 +1,70 @@
+/*
+ * 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 BaseModel from '../base/base.model.js';
+
+/**
+ * SentimentTopic - A class representing a sentiment analysis topic.
+ * Topics define what to analyze (e.g., "BMW XM Latest", "2026 Corvette Stingray").
+ *
+ * @class SentimentTopic
+ * @extends BaseModel
+ */
+class SentimentTopic extends BaseModel {
+  static ENTITY_NAME = 'SentimentTopic';
+
+  /**
+   * Adds a sub-prompt to the topic.
+   * @param {string} prompt - The prompt to add.
+   * @returns {this} The current instance for chaining.
+   */
+  addSubPrompt(prompt) {
+    const subPrompts = this.getSubPrompts?.() ?? this.subPrompts ?? [];
+    const updated = [...subPrompts, prompt];
+    if (this.setSubPrompts) {
+      this.setSubPrompts(updated);
+    } else {
+      this.subPrompts = updated;
+    }
+    return this;
+  }
+
+  /**
+   * Removes a sub-prompt from the topic.
+   * @param {string} prompt - The prompt to remove.
+   * @returns {this} The current instance for chaining.
+   */
+  removeSubPrompt(prompt) {
+    const subPrompts = this.getSubPrompts?.() ?? this.subPrompts ?? [];
+    const filtered = subPrompts.filter((p) => p !== prompt);
+    if (this.setSubPrompts) {
+      this.setSubPrompts(filtered);
+    } else {
+      this.subPrompts = filtered;
+    }
+    return this;
+  }
+
+  /**
+   * Generates the composite keys for remove/update operations.
+   * Required for entities with composite primary keys.
+   * @returns {Object} - The composite keys (siteId + topicId).
+   */
+  generateCompositeKeys() {
+    return {
+      siteId: this.getSiteId(),
+      topicId: this.getTopicId(),
+    };
+  }
+}
+
+export default SentimentTopic;

package/src/models/sentiment-topic/sentiment-topic.schema.js

@@ -0,0 +1,76 @@
+/*
+ * 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.
+ */
+
+/* c8 ignore start */
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import SentimentTopic from './sentiment-topic.model.js';
+import SentimentTopicCollection from './sentiment-topic.collection.js';
+
+/*
+Schema Doc: https://electrodb.dev/en/modeling/schema/
+Attribute Doc: https://electrodb.dev/en/modeling/attributes/
+Indexes Doc: https://electrodb.dev/en/modeling/indexes/
+
+Data Access Patterns:
+1. Get all topics for a site: allBySiteId(siteId)
+2. Get a specific topic: findById(siteId, topicId)
+3. Get enabled topics: allBySiteIdEnabled(siteId) - uses FilterExpression
+
+Primary Key (Composite):
+- Partition Key (PK): siteId
+- Sort Key (SK): topicId
+- Provides natural uniqueness for siteId + topicId combinations
+
+No GSI needed - all queries are site-scoped with FilterExpression
+*/
+
+const schema = new SchemaBuilder(SentimentTopic, SentimentTopicCollection)
+  .withPrimaryPartitionKeys(['siteId'])
+  .withPrimarySortKeys(['topicId'])
+  .addReference('belongs_to', 'Site')
+  .addAttribute('topicId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    default: () => crypto.randomUUID(),
+  })
+  .addAttribute('name', {
+    type: 'string',
+    required: true,
+    validate: (value) => hasText(value),
+  })
+  .addAttribute('description', {
+    type: 'string',
+    required: false,
+  })
+  .addAttribute('subPrompts', {
+    type: 'list',
+    items: { type: 'string' },
+    required: true,
+    default: [],
+  })
+  .addAttribute('enabled', {
+    type: 'boolean',
+    required: true,
+    default: true,
+  })
+  .addAttribute('createdBy', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    default: 'system',
+  });
+
+export default schema.build();