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

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [@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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.71.2",
+  "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/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 };