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): Opportunity;
+  setScopeType(scopeType: 'brand'): 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,38 @@ 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 (Boolean(scopeType) !== Boolean(scopeId)) {
+      throw new ValidationError('scopeType and scopeId must both be set or both be absent');
+    }
+    return super.create(item, options);
+  }
+
+  /**
+   * 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

@@ -37,6 +37,10 @@ class Opportunity extends BaseModel {
     RESOLVED: 'RESOLVED',
   };
 
+  static SCOPE_TYPES = {
+    BRAND: 'brand',
+  };
+
   /**
    * 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

@@ -382,6 +382,67 @@ 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',
+    };
+
+    it('returns only opportunities matching the given brandId', async () => {
+      // Create one opp for brand-a and one for brand-b on the same site
+      const oppA = await Opportunity.create({
+        ...scopedOpportunityBase,
+        title: 'Brand A Opportunity',
+        scopeType: 'brand',
+        scopeId: BRAND_A_ID,
+      });
+      const 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,7 @@ 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:-v1.67.8}
+    image: ${MYSTICAT_DATA_SERVICE_REPOSITORY:-682033462621.dkr.ecr.us-east-1.amazonaws.com/mysticat-data-service}:${MYSTICAT_DATA_SERVICE_TAG:-v5.1.1}
     depends_on:
       db:
         condition: service_healthy

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

@@ -12,6 +12,7 @@
 
 import { expect, use as chaiUse } from 'chai';
 import chaiAsPromised from 'chai-as-promised';
+import { stub } from 'sinon';
 import sinonChai from 'sinon-chai';
 
 import Opportunity from '../../../../src/models/opportunity/opportunity.model.js';
@@ -70,4 +71,69 @@ describe('OpportunityCollection', () => {
       expect(model).to.be.an('object');
     });
   });
+
+  describe('create', () => {
+    it('throws ValidationError when scopeType is set but scopeId is absent', async () => {
+      await expect(
+        instance.create({ type: 'content', scopeType: 'brand' }),
+      ).to.be.rejectedWith('scopeType and scopeId must both be set or both be absent');
+    });
+
+    it('throws ValidationError when scopeId is set but scopeType is absent', async () => {
+      await expect(
+        instance.create({ type: 'content', scopeId: '11111111-1111-1111-1111-111111111111' }),
+      ).to.be.rejectedWith('scopeType and scopeId must both be set or both be absent');
+    });
+
+    it('passes co-presence check when both scopeType and scopeId are set', async () => {
+      // Co-presence check passes — mock create succeeds without complaining.
+      await expect(
+        instance.create({ scopeType: 'brand', scopeId: '11111111-1111-1111-1111-111111111111' }),
+      ).to.be.fulfilled;
+    });
+
+    it('passes co-presence check when neither scopeType nor scopeId is set', async () => {
+      // Neither present — co-presence check passes and mock create succeeds.
+      await expect(
+        instance.create({ type: 'content' }),
+      ).to.be.fulfilled;
+    });
+
+    it('handles null item gracefully by delegating to super.create', async () => {
+      // null item: co-presence check skips (both undefined → equal), super.create handles it.
+      await expect(instance.create(null)).to.be.rejectedWith(/Failed to create/);
+    });
+  });
+
+  describe('allByScope', () => {
+    it('throws an error if scopeType is not provided', async () => {
+      await expect(instance.allByScope()).to.be.rejectedWith('allByScope: scopeType is required');
+    });
+
+    it('throws an error if scopeId is not provided', async () => {
+      await expect(instance.allByScope('brand')).to.be.rejectedWith('allByScope: scopeId is required');
+    });
+
+    it('delegates to allByIndexKeys with the correct arguments', async () => {
+      const mockOpportunity = { getOpportunityId: () => 'op-111' };
+      instance.allByIndexKeys = stub().resolves([mockOpportunity]);
+
+      const BRAND_UUID = 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa';
+      const result = await instance.allByScope('brand', BRAND_UUID);
+
+      expect(instance.allByIndexKeys).to.have.been.calledOnceWith({
+        scopeType: 'brand',
+        scopeId: BRAND_UUID,
+      });
+      expect(result).to.deep.equal([mockOpportunity]);
+    });
+
+    it('returns an empty array when no opportunities match the scope', async () => {
+      instance.allByIndexKeys = stub().resolves([]);
+
+      const result = await instance.allByScope('brand', 'cccccccc-cccc-4ccc-cccc-cccccccccccc');
+
+      expect(result).to.be.an('array').with.lengthOf(0);
+    });
+  });
 });

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

@@ -384,4 +384,43 @@ describe('OpportunityModel', () => {
       expect(instance.record.data).to.deep.equal({ newInfo: 'updatedInfo' });
     });
   });
+
+  describe('getScopeType and setScopeType', () => {
+    it('returns undefined when scopeType is not set', () => {
+      expect(instance.getScopeType()).to.be.undefined;
+    });
+
+    it('returns the scopeType value', () => {
+      mockRecord.scopeType = 'brand';
+      expect(instance.getScopeType()).to.equal('brand');
+    });
+
+    it('sets the scopeType value', () => {
+      instance.setScopeType('brand');
+      expect(instance.record.scopeType).to.equal('brand');
+    });
+  });
+
+  describe('getScopeId and setScopeId', () => {
+    it('returns undefined when scopeId is not set', () => {
+      expect(instance.getScopeId()).to.be.undefined;
+    });
+
+    it('returns the scopeId value', () => {
+      mockRecord.scopeId = 'brand-uuid-123';
+      expect(instance.getScopeId()).to.equal('brand-uuid-123');
+    });
+
+    it('sets the scopeId value', () => {
+      instance.setScopeId('brand-uuid-456');
+      expect(instance.record.scopeId).to.equal('brand-uuid-456');
+    });
+  });
+
+  describe('SCOPE_TYPES', () => {
+    it('defines expected scope type constants', () => {
+      expect(Opportunity.SCOPE_TYPES.BRAND).to.equal('brand');
+      expect(Opportunity.SCOPE_TYPES.SITE).to.be.undefined;
+    });
+  });
 });