@adobe/spacecat-shared-data-access 3.59.0 → 3.61.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@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
+
+* **data-access:** add llmBackend field to Organization entity ([#1588](https://github.com/adobe/spacecat-shared/issues/1588)) ([ebccbe5](https://github.com/adobe/spacecat-shared/commit/ebccbe55688fb4b8fb3ffd76cc29650c2cc2fc65)), closes [mysticat-data-service#534](https://github.com/adobe/mysticat-data-service/issues/534)
+
 ## [@adobe/spacecat-shared-data-access-v3.59.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.58.0...@adobe/spacecat-shared-data-access-v3.59.0) (2026-05-07)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.59.0",
+  "version": "3.61.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/organization.model.js

@@ -24,7 +24,15 @@ class Organization extends BaseModel {
 
   static IMS_ORG_ID_REGEX = /[a-z0-9]{24}@AdobeOrg/i;
 
-  // add your custom methods or overrides here
+  static LLM_BACKEND_AZURE = 'azure';
+
+  static LLM_BACKEND_BEDROCK = 'bedrock';
+
+  static LLM_BACKENDS = ['azure', 'bedrock'];
+
+  getLlmBackend() {
+    return this.record.llmBackend ?? Organization.LLM_BACKEND_AZURE;
+  }
 }
 
 export default Organization;

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

@@ -40,6 +40,10 @@ const schema = new SchemaBuilder(Organization, OrganizationCollection)
     type: 'string',
     validate: (value) => !value || Organization.IMS_ORG_ID_REGEX.test(value),
   })
+  .addAttribute('llmBackend', {
+    type: Organization.LLM_BACKENDS,
+    validate: (value) => !value || Organization.LLM_BACKENDS.includes(value),
+  })
   .addAttribute('fulfillableItems', {
     type: 'any',
     validate: (value) => !value || isNonEmptyObject(value),