@adobe/spacecat-shared-data-access 3.71.1 → 3.72.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [@adobe/spacecat-shared-data-access-v3.72.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.71.2...@adobe/spacecat-shared-data-access-v3.72.0) (2026-05-27)
+
+### Features
+
+* **data-access:** add Preflight entity with AsyncJob relationship (SITES-45417) ([2b57e6a](https://github.com/adobe/spacecat-shared/commit/2b57e6a1af8de07cee588409faab0ec4827a5a7d))
+
+### Bug Fixes
+
+* **data-access:** mint UUID v7 ids to match DB schema default ([#1633](https://github.com/adobe/spacecat-shared/issues/1633)) ([5c8f6fc](https://github.com/adobe/spacecat-shared/commit/5c8f6fcd454975703b4f670c0f560f43a768736a))
+
+## [@adobe/spacecat-shared-data-access-v3.71.2](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.71.1...@adobe/spacecat-shared-data-access-v3.71.2) (2026-05-26)
+
+### Bug Fixes
+
+*  (data-access) batch getAllFixesWithSuggestionsByOpportunityId (SITES-45307) ([#1619](https://github.com/adobe/spacecat-shared/issues/1619)) ([608f4cd](https://github.com/adobe/spacecat-shared/commit/608f4cda59af41c701426b8b53c29770efd42a1c))
+
 ## [@adobe/spacecat-shared-data-access-v3.71.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.71.0...@adobe/spacecat-shared-data-access-v3.71.1) (2026-05-25)
 
 ### Bug Fixes

package/package.json

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

package/src/models/base/entity.registry.js

@@ -43,6 +43,7 @@ import SiteTopPageCollection from '../site-top-page/site-top-page.collection.js'
 import SuggestionCollection from '../suggestion/suggestion.collection.js';
 import SuggestionGrantCollection from '../suggestion-grant/suggestion-grant.collection.js';
 import PageIntentCollection from '../page-intent/page-intent.collection.js';
+import PreflightCollection from '../preflight/preflight.collection.js';
 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';
@@ -83,6 +84,7 @@ import SiteTopPageSchema from '../site-top-page/site-top-page.schema.js';
 import SuggestionSchema from '../suggestion/suggestion.schema.js';
 import SuggestionGrantSchema from '../suggestion-grant/suggestion-grant.schema.js';
 import PageIntentSchema from '../page-intent/page-intent.schema.js';
+import PreflightSchema from '../preflight/preflight.schema.js';
 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';
@@ -218,6 +220,7 @@ EntityRegistry.registerEntity(SiteTopPageSchema, SiteTopPageCollection);
 EntityRegistry.registerEntity(SuggestionSchema, SuggestionCollection);
 EntityRegistry.registerEntity(SuggestionGrantSchema, SuggestionGrantCollection);
 EntityRegistry.registerEntity(PageIntentSchema, PageIntentCollection);
+EntityRegistry.registerEntity(PreflightSchema, PreflightCollection);
 EntityRegistry.registerEntity(ReportSchema, ReportCollection);
 EntityRegistry.registerEntity(TrialUserSchema, TrialUserCollection);
 EntityRegistry.registerEntity(TrialUserActivitySchema, TrialUserActivityCollection);

package/src/models/base/schema.builder.js

@@ -15,6 +15,7 @@ import {
 } from '@adobe/spacecat-shared-utils';
 
 import { SchemaBuilderError } from '../../errors/index.js';
+import { uuidv7 } from '../../util/uuid.js';
 import {
   decapitalize,
   entityNameToAllPKValue,
@@ -29,17 +30,15 @@ import Schema from './schema.js';
 
 const DEFAULT_SERVICE_NAME = 'SpaceCat';
 
-/**
- * ID attribute configuration object.
- * Ensures a UUID-based "primary key".
- * @type {object}
- */
+// The DB column default is `uuid_generate_v7()` (mysticat-data-service migration
+// 20250130000001_initial_setup.sql). We mint v7 client-side so the in-memory
+// record matches what the DB would have minted — sortable, locality-friendly.
 const ID_ATTRIBUTE_DATA = {
   type: 'string',
   postgrestField: 'id',
   required: true,
   readOnly: true,
-  default: () => crypto.randomUUID(),
+  default: () => uuidv7(),
   validate: (value) => isValidUUID(value),
 };
 

package/src/models/fix-entity/fix-entity.collection.js

@@ -177,69 +177,104 @@ class FixEntityCollection extends BaseCollection {
 
     try {
       const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
-      const suggestionCollection = this.entityRegistry.getCollection('SuggestionCollection');
 
-      // Query fix entity suggestions by opportunity ID and created date
       const fixEntitySuggestions = await fixEntitySuggestionCollection
         .allByOpportunityIdAndFixEntityCreatedDate(opportunityId, fixEntityCreatedDate);
 
-      if (fixEntitySuggestions.length === 0) {
-        return [];
+      return this.#buildFixesWithSuggestions(fixEntitySuggestions);
+    } catch (error) {
+      if (error instanceof DataAccessError) {
+        throw error;
       }
+      this.log.error('Failed to get all fixes with suggestions by created date', error);
+      throw new DataAccessError('Failed to get all fixes with suggestions by created date', this, error);
+    }
+  }
 
-      // Group suggestions by fix entity ID
-      const suggestionsByFixEntityId = {};
-      const fixEntityIds = new Set();
+  /**
+   * Gets all fixes with their suggestions for a specific opportunity.
+   * Fetches all junction records for the opportunity, then batch-loads
+   * fix entities and suggestions. Actual PostgREST call count is
+   * 1 + ceil(N/50) + ceil(M/50) due to batchGetByKeys chunking.
+   *
+   * @async
+   * @param {string} opportunityId - The ID of the opportunity.
+   * @returns {Promise<Array>} - A promise that resolves to an array of objects containing:
+   *   - fixEntity: The FixEntity model
+   *   - suggestions: Array of associated Suggestion models
+   * @throws {DataAccessError} - Throws an error if the query fails.
+   * @throws {ValidationError} - Throws an error if opportunityId is not provided.
+   */
+  async getAllFixesWithSuggestionsByOpportunityId(opportunityId) {
+    guardId('opportunityId', opportunityId, 'FixEntityCollection');
 
-      for (const fixEntitySuggestion of fixEntitySuggestions) {
-        const fixEntityId = fixEntitySuggestion.getFixEntityId();
-        const suggestionId = fixEntitySuggestion.getSuggestionId();
+    try {
+      const fixEntitySuggestionCollection = this.entityRegistry.getCollection('FixEntitySuggestionCollection');
 
-        fixEntityIds.add(fixEntityId);
+      const fixEntitySuggestions = await fixEntitySuggestionCollection
+        .allByIndexKeys({ opportunityId });
 
-        if (!suggestionsByFixEntityId[fixEntityId]) {
-          suggestionsByFixEntityId[fixEntityId] = [];
-        }
-        suggestionsByFixEntityId[fixEntityId].push(suggestionId);
+      return this.#buildFixesWithSuggestions(fixEntitySuggestions);
+    } catch (error) {
+      if (error instanceof DataAccessError) {
+        throw error;
       }
+      this.log.error('Failed to get all fixes with suggestions by opportunity ID', error);
+      throw new DataAccessError('Failed to get all fixes with suggestions by opportunity ID', this, error);
+    }
+  }
 
-      // Get all fix entities
-      const fixEntities = await this.batchGetByKeys(
-        Array.from(fixEntityIds).map((id) => ({ [this.idName]: id })),
-      );
-
-      // Get all suggestions
-      const allSuggestionIds = Object.values(suggestionsByFixEntityId).flat();
-      const suggestions = await suggestionCollection.batchGetByKeys(
-        allSuggestionIds.map((id) => ({ [suggestionCollection.idName]: id })),
-      );
-
-      // Create a map of suggestions by ID for quick lookup
-      const suggestionsById = {};
-      for (const suggestion of suggestions.data) {
-        suggestionsById[suggestion.getId()] = suggestion;
-      }
+  async #buildFixesWithSuggestions(fixEntitySuggestions) {
+    if (fixEntitySuggestions.length === 0) {
+      return [];
+    }
+
+    const suggestionCollection = this.entityRegistry.getCollection('SuggestionCollection');
+
+    const suggestionsByFixEntityId = {};
+    const fixEntityIds = new Set();
+
+    for (const fixEntitySuggestion of fixEntitySuggestions) {
+      const fixEntityId = fixEntitySuggestion.getFixEntityId();
+      const suggestionId = fixEntitySuggestion.getSuggestionId();
+
+      fixEntityIds.add(fixEntityId);
 
-      // Combine fix entities with their suggestions
-      const result = [];
-      for (const fixEntity of fixEntities.data) {
-        const fixEntityId = fixEntity.getId();
-        const suggestionIds = suggestionsByFixEntityId[fixEntityId] || [];
-        const suggestionsForFixEntity = suggestionIds
-          .map((id) => suggestionsById[id])
-          .filter(Boolean);
-
-        result.push({
-          fixEntity,
-          suggestions: suggestionsForFixEntity,
-        });
+      if (!suggestionsByFixEntityId[fixEntityId]) {
+        suggestionsByFixEntityId[fixEntityId] = [];
       }
+      suggestionsByFixEntityId[fixEntityId].push(suggestionId);
+    }
 
-      return result;
-    } catch (error) {
-      this.log.error('Failed to get all fixes with suggestions by created date', error);
-      throw new DataAccessError('Failed to get all fixes with suggestions by created date', this, error);
+    const fixEntities = await this.batchGetByKeys(
+      Array.from(fixEntityIds).map((id) => ({ [this.idName]: id })),
+    );
+
+    const allSuggestionIds = Object.values(suggestionsByFixEntityId).flat();
+    const suggestions = await suggestionCollection.batchGetByKeys(
+      allSuggestionIds.map((id) => ({ [suggestionCollection.idName]: id })),
+    );
+
+    const suggestionsById = {};
+    for (const suggestion of suggestions.data) {
+      suggestionsById[suggestion.getId()] = suggestion;
+    }
+
+    const result = [];
+    for (const fixEntity of fixEntities.data) {
+      const fixEntityId = fixEntity.getId();
+      const suggestionIds = suggestionsByFixEntityId[fixEntityId] || [];
+      const suggestionsForFixEntity = suggestionIds
+        .map((id) => suggestionsById[id])
+        .filter(Boolean);
+
+      result.push({
+        fixEntity,
+        suggestions: suggestionsForFixEntity,
+      });
     }
+
+    return result;
   }
 }
 

package/src/models/fix-entity/index.d.ts

@@ -40,4 +40,6 @@ export interface FixEntityCollection extends BaseCollection<FixEntity> {
   findByOpportunityIdAndStatus(opportunityId: string, status: string): Promise<FixEntity | null>;
   getSuggestionsByFixEntityId(fixEntityId: string): Promise<{data: Array<Suggestion>, unprocessed: Array<string>}>;
   setSuggestionsForFixEntity(opportunityId: string, fixEntity: FixEntity, suggestions: Array<Suggestion>): Promise<{createdItems: Array<FixEntitySuggestion>, errorItems: Array<FixEntitySuggestion>, removedCount: number}>;
+  getAllFixesWithSuggestionByCreatedAt(opportunityId: string, fixEntityCreatedDate: string): Promise<Array<{fixEntity: FixEntity, suggestions: Array<Suggestion>}>>;
+  getAllFixesWithSuggestionsByOpportunityId(opportunityId: string): Promise<Array<{fixEntity: FixEntity, suggestions: Array<Suggestion>}>>;
 }

package/src/models/index.js

@@ -43,6 +43,7 @@ export * from './site/index.js';
 export * from './suggestion/index.js';
 export * from './suggestion-grant/index.js';
 export * from './page-intent/index.js';
+export * from './preflight/index.js';
 export * from './report/index.js';
 export * from './trial-user/index.js';
 export * from './trial-user-activity/index.js';

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

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 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 { AsyncJob, BaseCollection, BaseModel, Site } from '../index.js';
+
+export interface Preflight extends BaseModel {
+    getSiteId(): string;
+    getSite(): Promise<Site>;
+    getAsyncJobId(): string;
+    getAsyncJob(): Promise<AsyncJob>;
+    getUrl(): string;
+    getStatus(): string;
+    getCreatedBy(): { email: string; displayName?: string };
+    getStartedAt(): string | null;
+    getEndedAt(): string | null;
+    getResult(): object | null;
+    getError(): { code: string; message: string } | null;
+
+    setUrl(url: string): Preflight;
+    setStatus(status: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELLED'): Preflight;
+    setCreatedBy(createdBy: { email: string; displayName?: string }): Preflight;
+    setStartedAt(startedAt: string): Preflight;
+    setEndedAt(endedAt: string): Preflight;
+    setResult(result: object): Preflight;
+    setError(error: { code: string; message: string }): Preflight;
+}
+
+export interface PreflightCollection extends BaseCollection<Preflight> {
+    allBySiteId(siteId: string): Promise<Preflight[]>;
+    findBySiteId(siteId: string): Promise<Preflight | null>;
+    findByAsyncJobId(asyncJobId: string): Promise<Preflight | null>;
+    allBySiteIdAndUrl(siteId: string, url?: string): Promise<Preflight[]>;
+}

package/src/models/preflight/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 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 Preflight from './preflight.model.js';
+import PreflightCollection from './preflight.collection.js';
+
+export {
+  Preflight,
+  PreflightCollection,
+};

package/src/models/preflight/preflight.collection.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2025 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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * PreflightCollection - A collection class responsible for managing Preflight entities.
+ * Extends the BaseCollection to provide specific methods for interacting with Preflight records.
+ *
+ * allBySiteId(siteId) is auto-generated from the BELONGS_TO Site reference in the schema.
+ *
+ * @class PreflightCollection
+ * @extends BaseCollection
+ */
+class PreflightCollection extends BaseCollection {
+  static COLLECTION_NAME = 'PreflightCollection';
+
+  /**
+   * Returns all preflights for a site, optionally filtered by URL.
+   * URL filtering is applied in-memory; volume is bounded by AsyncJob lifecycle
+   * (preflights cascade-delete when their backing AsyncJob is removed).
+   *
+   * @param {string} siteId - The site ID to query.
+   * @param {string} [url] - Optional URL to filter by.
+   * @returns {Promise<Preflight[]>}
+   */
+  async allBySiteIdAndUrl(siteId, url) {
+    const all = await this.allBySiteId(siteId);
+    if (!url) {
+      return all;
+    }
+    return all.filter((p) => p.getUrl() === url);
+  }
+}
+
+export default PreflightCollection;

package/src/models/preflight/preflight.model.js

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025 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';
+
+/**
+ * Preflight - A class representing a Preflight entity.
+ * Provides methods to access and manipulate Preflight-specific data.
+ *
+ * @class Preflight
+ * @extends BaseModel
+ */
+class Preflight extends BaseModel {
+  static ENTITY_NAME = 'Preflight';
+
+  static Status = {
+    IN_PROGRESS: 'IN_PROGRESS',
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+    CANCELLED: 'CANCELLED',
+  };
+
+  toJSON() {
+    const json = super.toJSON();
+    // asyncJobId is an internal FK reference — never exposed to API consumers
+    delete json.asyncJobId;
+    return json;
+  }
+}
+
+export default Preflight;

package/src/models/preflight/preflight.schema.js

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2025 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 {
+  isObject, isValidUrl, isIsoDate,
+} from '@adobe/spacecat-shared-utils';
+import SchemaBuilder from '../base/schema.builder.js';
+import Preflight from './preflight.model.js';
+import PreflightCollection from './preflight.collection.js';
+
+const schema = new SchemaBuilder(Preflight, PreflightCollection)
+  .addReference('belongs_to', 'Site', [], { required: true })
+  .addReference('belongs_to', 'AsyncJob', [], { required: true })
+  .addAttribute('url', {
+    type: 'string',
+    required: true,
+    validate: (value) => isValidUrl(value) && value.length <= 2048,
+  })
+  .addAttribute('status', {
+    type: Object.values(Preflight.Status),
+    required: true,
+    default: Preflight.Status.IN_PROGRESS,
+  })
+  .addAttribute('createdBy', {
+    type: 'map',
+    required: true,
+    validate: (value) => isObject(value) && typeof value.email === 'string' && value.email.length > 0,
+  })
+  .addAttribute('startedAt', {
+    type: 'string',
+    validate: (value) => !value || isIsoDate(value),
+  })
+  .addAttribute('endedAt', {
+    type: 'string',
+    validate: (value) => !value || isIsoDate(value),
+  })
+  .addAttribute('result', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('error', {
+    type: 'map',
+    validate: (value) => !value || (isObject(value) && typeof value.code === 'string' && value.code.length > 0 && typeof value.message === 'string' && value.message.length > 0),
+  });
+
+export default schema.build();

package/src/util/uuid.js

@@ -0,0 +1,43 @@
+/*
+ * 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 { randomBytes } from 'crypto';
+
+// Mirrors the database's `uuid_generate_v7()` plpgsql function defined in
+// mysticat-data-service migration 20250130000001_initial_setup.sql so client-
+// minted ids share the same time-sortable layout as DB-defaulted rows. The
+// schema has been v7-by-design since Jan 2025; this keeps the ORM aligned.
+/* eslint-disable no-bitwise */
+function uuidv7() {
+  // Every byte is overwritten below (0-5 from the timestamp, 6-15 from
+  // randomBytes), so allocUnsafe avoids the zero-fill that alloc would do.
+  const bytes = Buffer.allocUnsafe(16);
+  const ms = BigInt(Date.now());
+
+  bytes[0] = Number((ms >> 40n) & 0xffn);
+  bytes[1] = Number((ms >> 32n) & 0xffn);
+  bytes[2] = Number((ms >> 24n) & 0xffn);
+  bytes[3] = Number((ms >> 16n) & 0xffn);
+  bytes[4] = Number((ms >> 8n) & 0xffn);
+  bytes[5] = Number(ms & 0xffn);
+
+  randomBytes(10).copy(bytes, 6);
+
+  bytes[6] = (bytes[6] & 0x0f) | 0x70;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+  const hex = bytes.toString('hex');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/* eslint-enable no-bitwise */
+
+export { uuidv7 };