@adobe/spacecat-shared-data-access 3.60.0 → 3.62.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.62.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.61.0...@adobe/spacecat-shared-data-access-v3.62.0) (2026-05-12)
+
+### Features
+
+* **data-access:** add semrushWorkspaceId attribute to Organization ([#1602](https://github.com/adobe/spacecat-shared/issues/1602)) ([79a5d82](https://github.com/adobe/spacecat-shared/commit/79a5d825c2a3cb436d894f5bea90a0a4e230167b))
+
+## [@adobe/spacecat-shared-data-access-v3.61.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.60.0...@adobe/spacecat-shared-data-access-v3.61.0) (2026-05-12)
+
+### Features
+
+* **data-access:** add scopeType and scopeId to Opportunity model ([#1576](https://github.com/adobe/spacecat-shared/issues/1576)) ([3f0f8f2](https://github.com/adobe/spacecat-shared/commit/3f0f8f25c058c5c885fd1f553dd43e4ed07b3d67)), closes [#32-42](https://github.com/adobe/spacecat-shared/issues/32-42)
+
 ## [@adobe/spacecat-shared-data-access-v3.60.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.59.0...@adobe/spacecat-shared-data-access-v3.60.0) (2026-05-11)
 
 ### Features

package/package.json

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

package/src/models/opportunity/index.d.ts

@@ -21,27 +21,31 @@ 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;
@@ -49,6 +53,7 @@ export interface Opportunity extends BaseModel {
 }
 
 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[]>;

package/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;

package/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.

package/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();

package/src/models/organization/index.d.ts

@@ -19,6 +19,7 @@ export interface Organization extends BaseModel {
   getFulfillableItems(): object;
   getImsOrgId(): string;
   getName(): string;
+  getSemrushWorkspaceId(): string;
   getSites(): Promise<Site[]>;
   getProjects(): Promise<Project[]>;
   getEntitlements(): Promise<Entitlement[]>;
@@ -28,9 +29,12 @@ export interface Organization extends BaseModel {
   setFulfillableItems(fulfillableItems: object): Organization;
   setImsOrgId(imsOrgId: string): Organization;
   setName(name: string): Organization;
+  setSemrushWorkspaceId(semrushWorkspaceId: string): Organization;
 }
 
 export interface OrganizationCollection extends BaseCollection<Organization> {
   allByImsOrgId(imsOrgId: string): Promise<Organization[]>;
+  allBySemrushWorkspaceId(semrushWorkspaceId: string): Promise<Organization[]>;
   findByImsOrgId(imsOrgId: string): Promise<Organization | null>;
+  findBySemrushWorkspaceId(semrushWorkspaceId: string): Promise<Organization | null>;
 }

package/src/models/organization/organization.schema.js

@@ -12,7 +12,7 @@
 
 /* c8 ignore start */
 
-import { isNonEmptyObject } from '@adobe/spacecat-shared-utils';
+import { hasText, isNonEmptyObject } from '@adobe/spacecat-shared-utils';
 
 import { Config, DEFAULT_CONFIG, validateConfiguration } from '../site/config.js';
 import SchemaBuilder from '../base/schema.builder.js';
@@ -48,6 +48,19 @@ const schema = new SchemaBuilder(Organization, OrganizationCollection)
     type: 'any',
     validate: (value) => !value || isNonEmptyObject(value),
   })
-  .addAllIndex(['imsOrgId']);
+  .addAttribute('semrushWorkspaceId', {
+    type: 'string',
+    // Minimum guard: reject empty / whitespace-only strings. Full format
+    // validation deferred until Semrush confirms the workspace-ID format.
+    // Use value == null (loose) so undefined and null short-circuit, but
+    // empty string ('') falls through to hasText() which rejects it.
+    validate: (value) => value == null || hasText(value),
+  })
+  .addAllIndex(['imsOrgId'])
+  // Uniqueness is enforced at the DB level via the UNIQUE constraint on
+  // organizations.semrush_workspace_id (mysticat-data-service migration
+  // 20260525000000), so findBySemrushWorkspaceId is semantically guaranteed
+  // to return at most one row.
+  .addAllIndex(['semrushWorkspaceId']);
 
 export default schema.build();