feat(data-access): add scopeType and scopeId to Opportunity model

packages/spacecat-shared-data-access/src/models/opportunity/index.d.ts

@@ -21,34 +21,39 @@ export interface Opportunity extends BaseModel {
   getAuditId(): string;
   getData(): object;
   getDescription(): string;
+  getFixEntities(): Promise<FixEntity[]>;
   getGuidance(): string;
+  getLastAuditedAt(): string;
   getOrigin(): string;
   getRunbook(): string;
+  getScopeId(): string | undefined;
+  getScopeType(): string | undefined;
   getSite(): Promise<Site>;
   getSiteId(): string;
   getStatus(): string;
-  getFixEntities(): Promise<FixEntity[]>;
   getSuggestions(): Promise<Suggestion[]>;
   getSuggestionsByStatus(status: string): Promise<Suggestion[]>;
   getSuggestionsByStatusAndRank(status: string, rank: string): Promise<Suggestion[]>;
-  getLastAuditedAt(): string;
   getTags(): string[];
   getTitle(): string;
   getType(): string;
   setAuditId(auditId: string): Opportunity;
   setData(data: object): Opportunity;
   setDescription(description: string): Opportunity;
-  setLastAuditedAt(lastAuditedAt: string): Opportunity;
   setGuidance(guidance: string): Opportunity;
+  setLastAuditedAt(lastAuditedAt: string): Opportunity;
   setOrigin(origin: string): Opportunity;
   setRunbook(runbook: string): Opportunity;
+  setScopeId(scopeId: string | null | undefined): Opportunity;
+  setScopeType(scopeType: 'brand' | null | undefined): Opportunity;
   setSiteId(siteId: string): Opportunity;
   setStatus(status: string): Opportunity;
   setTags(tags: string[]): Opportunity;
   setTitle(title: string): Opportunity;
 }
 
 export interface OpportunityCollection extends BaseCollection<Opportunity> {
+  allByScope(scopeType: string, scopeId: string): Promise<Opportunity[]>;
   allByAuditId(auditId: string): Promise<Opportunity[]>;
   allByAuditIdAndUpdatedAt(auditId: string, updatedAt: string): Promise<Opportunity[]>;
   allBySiteId(siteId: string): Promise<Opportunity[]>;

packages/spacecat-shared-data-access/src/models/opportunity/opportunity.collection.js

@@ -10,6 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import { ValidationError } from '../../errors/index.js';
 import BaseCollection from '../base/base.collection.js';
 
 /**
@@ -22,7 +25,91 @@ import BaseCollection from '../base/base.collection.js';
 class OpportunityCollection extends BaseCollection {
   static COLLECTION_NAME = 'OpportunityCollection';
 
-  // add custom methods here
+  /**
+   * Validates and creates a new Opportunity. Enforces that scopeType and scopeId
+   * must both be present or both be absent — a half-scoped record is invalid.
+   *
+   * @param {object} item - The opportunity data.
+   * @param {object} [options] - Optional create options (e.g. { upsert: true }).
+   * @returns {Promise<Opportunity>} The created opportunity instance.
+   */
+  async create(item, options) {
+    const { scopeType, scopeId } = item || {};
+    if (hasText(scopeType) !== hasText(scopeId)) {
+      throw new ValidationError('scopeType and scopeId must both be set or both be absent', this);
+    }
+    return super.create(item, options);
+  }
+
+  /**
+   * Validates and bulk-creates Opportunities. Enforces the scopeType/scopeId
+   * co-presence invariant on every item — half-scoped records are invalid.
+   *
+   * Overrides BaseCollection.createMany() which would otherwise bypass the
+   * single-item create() guard and persist invalid scope tuples directly.
+   *
+   * @param {object[]} items - The opportunity items to create.
+   * @param {...*} rest - Additional arguments forwarded to BaseCollection.createMany.
+   * @returns {Promise<*>} The result from BaseCollection.createMany.
+   */
+  async createMany(items, ...rest) {
+    if (Array.isArray(items)) {
+      for (const item of items) {
+        const { scopeType, scopeId } = item || {};
+        if (hasText(scopeType) !== hasText(scopeId)) {
+          throw new ValidationError('scopeType and scopeId must both be set or both be absent', this);
+        }
+      }
+    }
+    return super.createMany(items, ...rest);
+  }
+
+  /**
+   * Validates and updates an Opportunity by its keys. Enforces the scopeType/scopeId
+   * co-presence invariant: if either field appears in the update payload, both must
+   * be set or both must be absent — a half-scoped update is invalid.
+   *
+   * Note: this guard enforces co-presence but allows scope re-attribution
+   * (moving an opportunity from one scopeId to another within the same scopeType).
+   * scopeId is the tenant boundary; callers must verify authorization before mutating it.
+   *
+   * @param {object} keys - The key attributes identifying the record.
+   * @param {object} updates - The fields to update.
+   * @returns {Promise<void>}
+   */
+  async updateByKeys(keys, updates) {
+    const hasScopeType = updates != null && 'scopeType' in updates;
+    const hasScopeId = updates != null && 'scopeId' in updates;
+    // If either field is included in the update, both must be included together,
+    // and their combined values must satisfy co-presence (both set or both absent).
+    if (hasScopeType !== hasScopeId) {
+      throw new ValidationError('scopeType and scopeId must both be set or both be absent', this);
+    }
+    if (hasScopeType && hasScopeId) {
+      const { scopeType, scopeId } = updates;
+      if (hasText(scopeType) !== hasText(scopeId)) {
+        throw new ValidationError('scopeType and scopeId must both be set or both be absent', this);
+      }
+    }
+    return super.updateByKeys(keys, updates);
+  }
+
+  /**
+   * Returns all opportunities matching a given scope type and scope ID.
+   *
+   * @param {string} scopeType - The scope type (e.g. 'brand').
+   * @param {string} scopeId - The scope entity UUID.
+   * @returns {Promise<Opportunity[]>} The matching opportunities.
+   */
+  async allByScope(scopeType, scopeId) {
+    if (!hasText(scopeType)) {
+      throw new Error('allByScope: scopeType is required');
+    }
+    if (!hasText(scopeId)) {
+      throw new Error('allByScope: scopeId is required');
+    }
+    return this.allByIndexKeys({ scopeType, scopeId });
+  }
 }
 
 export default OpportunityCollection;

packages/spacecat-shared-data-access/src/models/opportunity/opportunity.model.js

@@ -10,6 +10,9 @@
  * governing permissions and limitations under the License.
  */
 
+import { hasText } from '@adobe/spacecat-shared-utils';
+
+import { ValidationError } from '../../errors/index.js';
 import BaseModel from '../base/base.model.js';
 
 /**
@@ -37,6 +40,27 @@ class Opportunity extends BaseModel {
     RESOLVED: 'RESOLVED',
   };
 
+  static SCOPE_TYPES = {
+    BRAND: 'brand',
+  };
+
+  /**
+   * Overrides BaseModel.save() to enforce the co-presence invariant: scopeType and scopeId
+   * must both be set or both be absent. Guards the setter+save path in addition to create().
+   *
+   * @returns {Promise<Opportunity>} The saved opportunity.
+   * @throws {ValidationError} When only one of scopeType / scopeId is set.
+   */
+  async save() {
+    if (hasText(this.getScopeType()) !== hasText(this.getScopeId())) {
+      throw new ValidationError(
+        'scopeType and scopeId must both be set or both be absent',
+        this,
+      );
+    }
+    return super.save();
+  }
+
   /**
    * Adds the given suggestions to this Opportunity. Sets this opportunity as the parent
    * of each suggestion, as such the opportunity ID does not need to be provided.

packages/spacecat-shared-data-access/src/models/opportunity/opportunity.schema.js

@@ -12,7 +12,9 @@
 
 /* c8 ignore start */
 
-import { isIsoDate, isNonEmptyObject, isValidUrl } from '@adobe/spacecat-shared-utils';
+import {
+  isIsoDate, isNonEmptyObject, isValidUrl, isValidUUID,
+} from '@adobe/spacecat-shared-utils';
 
 import SchemaBuilder from '../base/schema.builder.js';
 import Opportunity from './opportunity.model.js';
@@ -64,6 +66,15 @@ const schema = new SchemaBuilder(Opportunity, OpportunityCollection)
   .addAttribute('lastAuditedAt', {
     type: 'string',
     validate: (value) => !value || isIsoDate(value),
-  });
+  })
+  .addAttribute('scopeType', {
+    type: 'string',
+    validate: (value) => !value || Object.values(Opportunity.SCOPE_TYPES).includes(value),
+  })
+  .addAttribute('scopeId', {
+    type: 'string',
+    validate: (value) => !value || isValidUUID(value),
+  })
+  .addIndex({ composite: ['scopeId'] }, { composite: ['scopeType'] });
 
 export default schema.build();

packages/spacecat-shared-data-access/test/it/opportunity/opportunity.test.js

@@ -383,6 +383,74 @@ describe('Opportunity IT', async () => {
     expect(record2).to.eql(data[1]);
   });
 
+  describe('allByScope', () => {
+    const BRAND_A_ID = 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa';
+    const BRAND_B_ID = 'bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb';
+
+    const scopedOpportunityBase = {
+      siteId,
+      title: 'Scoped Opportunity',
+      description: 'Test for allByScope',
+      type: 'prerender',
+      origin: 'AI',
+      status: 'NEW',
+      updatedBy: 'system',
+    };
+
+    let oppA;
+    let oppB;
+
+    after(async () => {
+      await Promise.all([oppA?.remove(), oppB?.remove()].filter(Boolean));
+    });
+
+    it('returns only opportunities matching the given scope', async () => {
+      // Create one opp for brand-a and one for brand-b on the same site
+      oppA = await Opportunity.create({
+        ...scopedOpportunityBase,
+        title: 'Brand A Opportunity',
+        scopeType: 'brand',
+        scopeId: BRAND_A_ID,
+      });
+      oppB = await Opportunity.create({
+        ...scopedOpportunityBase,
+        title: 'Brand B Opportunity',
+        scopeType: 'brand',
+        scopeId: BRAND_B_ID,
+      });
+
+      const resultA = await Opportunity.allByScope('brand', BRAND_A_ID);
+      const resultB = await Opportunity.allByScope('brand', BRAND_B_ID);
+
+      const idSetA = resultA.map((o) => o.getId());
+      const idSetB = resultB.map((o) => o.getId());
+
+      expect(idSetA).to.include(oppA.getId());
+      expect(idSetA).to.not.include(oppB.getId());
+
+      expect(idSetB).to.include(oppB.getId());
+      expect(idSetB).to.not.include(oppA.getId());
+    });
+
+    it('returns an empty array when no opportunities match the scopeId', async () => {
+      const UNKNOWN_BRAND_ID = 'cccccccc-cccc-4ccc-cccc-cccccccccccc';
+      const result = await Opportunity.allByScope('brand', UNKNOWN_BRAND_ID);
+      expect(result).to.be.an('array').with.length(0);
+    });
+
+    it('rejects co-presence violation: scopeType set without scopeId', async () => {
+      await expect(
+        Opportunity.create({ ...scopedOpportunityBase, scopeType: 'brand' }),
+      ).to.be.rejectedWith('scopeType and scopeId must both be set or both be absent');
+    });
+
+    it('rejects co-presence violation: scopeId set without scopeType', async () => {
+      await expect(
+        Opportunity.create({ ...scopedOpportunityBase, scopeId: BRAND_A_ID }),
+      ).to.be.rejectedWith('scopeType and scopeId must both be set or both be absent');
+    });
+  });
+
   describe('addFixEntities', () => {
     it('creates fix entities with valid suggestions', async () => {
       const opportunity = await Opportunity.findById(sampleData.opportunities[2].getId());

packages/spacecat-shared-data-access/test/it/postgrest/docker-compose.yml

@@ -17,7 +17,20 @@ services:
 
   data-service:
     platform: ${MYSTICAT_DATA_SERVICE_PLATFORM:-linux/amd64}
-    image: ${MYSTICAT_DATA_SERVICE_REPOSITORY:-682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-data-service}:${MYSTICAT_DATA_SERVICE_TAG:-v5.1.1}
+    # Default tag is bumped here whenever a new schema migration requires a matching data-service
+    # image. The tag is supplemented by an immutable digest so CI cannot silently consume a
+    # re-pushed tag — if ECR re-publishes v5.1.1 with a different binary, the digest mismatch
+    # causes a hard pull failure instead of silent drift.
+    #
+    # To obtain or refresh the digest:
+    #   aws ecr describe-images \
+    #     --profile <your-profile> --region us-east-1 \
+    #     --repository-name mysticat-data-service \
+    #     --image-ids imageTag=v5.1.1 \
+    #     --query 'imageDetails[0].imageDigest' --output text
+    # Then export MYSTICAT_DATA_SERVICE_DIGEST=sha256:<the-digest> before npm run test:it,
+    # or set it in the .env file consumed by docker compose. Leave unset for local dev.
+    image: ${MYSTICAT_DATA_SERVICE_REPOSITORY:-682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-data-service}:${MYSTICAT_DATA_SERVICE_TAG:-v5.1.1}${MYSTICAT_DATA_SERVICE_DIGEST:+@${MYSTICAT_DATA_SERVICE_DIGEST}}
     depends_on:
       db:
         condition: service_healthy