feat: add brand sentiment guidelines

packages/spacecat-shared-data-access/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;

packages/spacecat-shared-data-access/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';

packages/spacecat-shared-data-access/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';

packages/spacecat-shared-data-access/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>;
+}

packages/spacecat-shared-data-access/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,
+};

packages/spacecat-shared-data-access/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;

packages/spacecat-shared-data-access/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;